Internal Event Subscriptions

Internal event subscriptions (also called App Event Subscriptions) are created when a Flow has a trigger that reacts to Internal Events and the flow is enabled. These subscriptions manage how Membrane receives and processes events from your application.

You can find the list of subscriptions and information about each of them here: App Event Subscriptions.

How Subscriptions Work

Internal event subscriptions connect your application's events to Flow triggers. When you enable a Flow that uses an App Event Trigger node, Membrane automatically:

1. Creates an App Event Subscription for the specified Internal Event and Customer.
2. If configured, makes an HTTP subscription request to your application's API.
3. Generates a unique webhook URL for receiving events.

The subscription is automatically disabled (and unsubscribed) when there are no more flows that need it.

Subscription Types

Global Webhook

Global webhooks provide a centralized way to send events to Membrane without per-customer subscriptions. With global webhooks, you send all events to a single webhook URI, and Membrane routes them to the appropriate customer based on:

• Authentication Token (Recommended) – Include the customer token in the Authorization header
• Tenant ID Formula – Extract customer ID from the event payload using a configured formula

Example request to a global webhook:

curl --request POST \
  --url https://api.integration.app/{GLOBAL_WEBHOOK_URI} \
  --header "Authorization: Bearer {CUSTOMER_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"eventType": "order.created", "orderId": "123"}'

Per-Customer Subscriptions

Per-customer subscriptions create individual webhook URLs for each customer. This approach is used when:

• Your application has an API that supports webhook registration
• You want to send events directly to customer-specific endpoints
• You need to track subscription status per customer

When configured, Membrane:

1. Makes an HTTP request to your application's subscription API
2. Provides a unique webhook URL in the request (available as {{webhookUri}} variable)
3. Expects your application to send events to that specific webhook URL
4. Tracks the subscription request and response for troubleshooting

Example subscription request configuration:

subscribeRequest:
  uri: https://api.yourapp.com/webhooks/subscribe
  method: POST
  headers:
    Authorization:
      $concat:
        - "Bearer "
        - $var: $.user.fields.apiKey
  body:
    webhook:
      $var: $.webhookUri

Subscription Lifecycle

Creation

App Event Subscriptions are created automatically when:

1. A Flow Instance is enabled that contains an App Event Trigger node
2. The App Event Type is configured and ready to receive events
3. The customer (user) context is available

Setup and Subscription

After creation, if a subscription request is configured:

1. Membrane builds the HTTP request using configured parameters
2. The request is sent to your application's webhook subscription endpoint
3. Your application should respond with success and begin sending events
4. The response is stored for troubleshooting

If no subscription request is configured (global webhook mode), the subscription is immediately active and ready to receive events.

Deactivation

Subscriptions are deactivated when:

• All Flows using the subscription are disabled or deleted
• The subscription is manually archived
• The customer is archived

When deactivated, if an unsubscribe request was configured, Membrane sends it to notify your application to stop sending events.

Automatic De-duplication

Membrane automatically de-duplicates subscriptions. If multiple Flow Instances need the same Internal Event Type for the same customer and instance key, only one subscription is created and shared between them.

For example:

• Flow A and Flow B both trigger on "Order Created" events for Customer X
• Only one App Event Subscription is created
• Both flows are launched when an event arrives
• The subscription remains active until both flows are disabled

Batch Events

If your application sends an array in the request body, Membrane treats it as multiple events:

# Single event
POST /webhooks/app-event-subscriptions/{UUID}
{"orderId": "123", "status": "completed"}

# Batch of events
POST /webhooks/app-event-subscriptions/{UUID}
[
  {"orderId": "123", "status": "completed"},
  {"orderId": "124", "status": "pending"}
]

For global webhooks with batch events, each event can be associated with a different customer by including customer identification in each event payload.

Monitoring and Troubleshooting

Viewing Subscriptions

Navigate to App Event Subscriptions to see:

• All active and inactive subscriptions
• Subscription status (subscribed/unsubscribed)
• The webhook URL for each subscription
• Subscription and unsubscription request/response history
• Associated App Event Type and customer

Viewing Events

Navigate to App Events to see:

• All received events
• Which subscription received each event
• Event payload and timestamp
• Which Flows were triggered
• Execution status of triggered Flows