Skip to main content
Webhook notifications let your backend react to events in your Membrane workspace — connections being created, disconnected, or archived.

​
Setup

Configure a webhook URL in the Console under Settings > Webhook Notifications. Membrane sends a POST request to your URL whenever a matching event occurs.

​
Event Types

​
Connection Events

EventWhen it fires
connection.createdA new connection is established (OAuth completed, API key saved)
connection.disconnectedA connection lost access (token expired, credentials revoked)
connection.reconnectedA previously disconnected connection is restored
connection.deletedA connection is archived

​
Flow Run Events

EventWhen it fires
flowRun.queuedA flow run is queued for execution
flowRun.startedA flow run begins executing
flowRun.completedA flow run finishes successfully
flowRun.failedA flow run fails with an error
flowRun.stoppedA flow run is manually stopped

​
Alert Events

EventWhen it fires
alert.createdAn alert is created or becomes ongoing

​
Payloads

Each webhook POST body contains an eventType field and a data object. The shape of data depends on the event category.

​
Connection events

{
  "eventType": "connection.created",
  "data": {
    "connection": {
      "id": "con_abc123",
      "integrationId": "int_xyz789",
      "integrationKey": "slack",
      "name": "Slack",
      "disconnected": false,
      "customerId": "customer-123"
    }
  }
}

​
Flow run events

{
  "eventType": "flowRun.completed",
  "data": {
    "flowRun": {
      "id": "fr_abc123",
      "connectionFlowId": "cf_xyz789",
      "integrationFlowId": "if_abc456",
      "state": "completed",
      "startTime": "2024-01-15T10:30:00.000Z",
      "endTime": "2024-01-15T10:30:05.123Z",
      "startNodeKey": "trigger",
      "launchedBy": { "type": "app-event-trigger" }
    }
  }
}
The flowRun.failed event includes an errors array on the flow run object with details about what went wrong.

​
Alert events

{
  "eventType": "alert.created",
  "data": {
    "alert": {
      "id": "alrt_abc123",
      "type": "connection_disconnected",
      "severity": "warning",
      "description": "Slack connection lost access",
      "status": "ongoing",
      "workspaceId": "ws_xyz789",
      "workspaceUrl": "https://console.getmembrane.com/w/org-workspace-id",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  }
}

​
Handling Webhooks

Example Express.js endpoint: 
app.post('/api/membrane-webhook', async (req, res) => {
  const { eventType, data } = req.body

  switch (eventType) {
    case 'connection.created':
      // Run an action on the new connection
      const membrane = new MembraneClient({ token: process.env.MEMBRANE_ACCESS_TOKEN })
      await membrane
        .action('send-slack-message')
        .run({ channel: 'general', text: 'Your app is now connected!' }, { connectionId: data.connection.id })
      break
    case 'connection.disconnected':
      // Notify user to reconnect
      break
    case 'flowRun.failed':
      // Log or alert on flow run failure
      console.error('Flow run failed', data.flowRun.errors)
      break
    case 'alert.created':
      // Forward alert to your monitoring system
      break
  }

  res.sendStatus(200)
})

​
Retry Behavior

If your endpoint returns a non-2xx status code, Membrane retries with exponential backoff.

​
See Also

  • Connections — connection lifecycle and management
  • Events — data events from external apps (distinct from webhook notifications)