Webhook Subscriptions

Webhook subscriptions allow you to receive real-time notifications when events occur on the Flowbrite platform.

Overview

Webhook subscriptions allow you to register a URL that Flowbrite will send HTTP POST requests to whenever a subscribed event occurs. This is useful for integrating Flowbrite with your own systems, such as updating your accounting software when a payment is sent or alerting your team when a conversion is booked.

Each subscription can listen to one or more event types. You can retrieve the list of available event types from the Reference Data endpoint.

Notification Delivery

Notifications are sent as HTTP POST requests with a JSON body.
If your endpoint returns a non-2xx status code, Flowbrite will retry the notification with exponential backoff.
You can monitor delivery status and redeliver failed notifications using the notification endpoints.

Subscriptions

Create a Subscription

POST/v1/webhook-subscriptions

Create a new webhook subscription. This endpoint requires the X-IDEMPOTENCY-KEY header.

Please refer to the Idempotency Guide for more information.

Request Body

Name
targetPlatform
Type
string
Type
Description
An optional label to identify the target platform (e.g. "Slack", "My App"). Max 1024 characters.
Name
targetUrl
Type
string
Required
Type
Description
The URL to send webhook notifications to. Must be a valid URL. Max 2048 characters.
Name
events
Type
string[]
Required
Type
Description
An array of event types to subscribe to. Must be valid event types from the webhook events endpoint.

Request

POST

/v1/webhook-subscriptions

  curl -X POST https://api.flowbrite.io/v1/webhook-subscriptions \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "targetPlatform": "My App",
    "targetUrl": "https://example.com/webhooks/flowbrite",
    "events": ["payment.sent", "conversion.exchanged", "inbound_funds.credited"]
  }'

Responses

201 - Created

400 - Bad Request

Example Responses

{
  "data": {
    "id": "whs_X01JTK7HABCDEF1234567890",
    "client": {
      "id": "cli_X01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "Joanna Bloggs Ltd"
    },
    "targetPlatform": "My App",
    "targetUrl": "https://example.com/webhooks/flowbrite",
    "events": ["payment.sent", "conversion.exchanged", "inbound_funds.credited"],
    "isActive": true,
    "unsubscribedOn": null,
    "signingSecret": "whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "auditHistory": {
      "version": 1,
      "created": {
        "by": {
          "id": "cu_X01JTK7H5REAMT5ND5HEGQ7B0KX",
          "name": "Joanna Bloggs"
        },
        "on": "2025-06-01T09:00:00",
        "withApiKey": "ak_X01JTK7HABCDEF1234567890"
      },
      "updated": {
        "by": null,
        "on": "2025-06-01T09:00:00",
        "withApiKey": null
      }
    }
  }
}

View a Subscription

GET/v1/webhook-subscriptions/{id}

Retrieve a webhook subscription.

Path Parameters

Name
id
Type
string
Required
Type
Description
The unique ID of the webhook subscription.

Request

GET

/v1/webhook-subscriptions/{id}

  curl -G https://api.flowbrite.io/v1/webhook-subscriptions/{id} \
  -H "X-API-KEY: {api_key}"

Responses

200 - OK

404 - Not Found

Example Responses

{
  "data": {
    "id": "whs_X01JTK7HABCDEF1234567890",
    "client": {
      "id": "cli_X01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "Joanna Bloggs Ltd"
    },
    "targetPlatform": "My App",
    "targetUrl": "https://example.com/webhooks/flowbrite",
    "events": ["payment.sent", "conversion.exchanged", "inbound_funds.credited"],
    "isActive": true,
    "unsubscribedOn": null,
    "auditHistory": {
      "version": 1,
      "created": {
        "by": {
          "id": "cu_X01JTK7H5REAMT5ND5HEGQ7B0KX",
          "name": "Joanna Bloggs"
        },
        "on": "2025-06-01T09:00:00",
        "withApiKey": "ak_X01JTK7HABCDEF1234567890"
      },
      "updated": {
        "by": null,
        "on": "2025-06-01T09:00:00",
        "withApiKey": null
      }
    }
  }
}

Search Subscriptions

GET/v1/webhook-subscriptions

Search for webhook subscriptions using the available search parameters.

Please refer to the Search Guide for information on how to construct queries.

Search Parameters

Show search fields

Request

GET

/v1/webhook-subscriptions

  curl -G https://api.flowbrite.io/v1/webhook-subscriptions \
  -H "X-API-KEY: {api_key}" \
  -d 'q=isActive==true' \
  -d "sortBy=auditHistory.created.on:DESC" \
  -d "offset=0" \
  -d "limit=10"

Responses

200 - OK

400 - Bad Request

Example Responses

{
  "data": [
    {
      "id": "whs_X01JTK7HABCDEF1234567890",
      "client": {
        "id": "cli_X01JTK7H3SZEEP3KVHA1ZFFRYDD",
        "name": "Joanna Bloggs Ltd"
      },
      "targetPlatform": "My App",
      "targetUrl": "https://example.com/webhooks/flowbrite",
      "events": ["payment.sent", "conversion.exchanged"],
      "isActive": true,
      "unsubscribedOn": null,
      "auditHistory": null
    }
  ],
  "meta": {
    "query": "isActive==true",
    "sortBy": ["auditHistory.created.on:DESC"],
    "offset": 0,
    "limit": 10,
    "count": 1,
    "totalCount": 1,
    "timestamp": "2025-06-01T09:00:00Z"
  }
}

Subscription Actions

The following endpoints allow you to manage the lifecycle of a webhook subscription. All require the X-IDEMPOTENCY-KEY header.

Pause

POST/v1/webhook-subscriptions/{id}/pause

Pause a webhook subscription. While paused, no notifications will be sent. Notifications that occur while paused are queued. This endpoint requires the X-IDEMPOTENCY-KEY header.

Path Parameters

Name
id
Type
string
Required
Type
Description
The unique ID of the webhook subscription.

Request

POST

/v1/webhook-subscriptions/{id}/pause

  curl -X POST https://api.flowbrite.io/v1/webhook-subscriptions/{id}/pause \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}"

Responses

200 - OK

Example Responses

{
  "data": {
    "id": "whs_X01JTK7HABCDEF1234567890",
    "isActive": false,
    "unsubscribedOn": null
  }
}

Rotate Secret

POST/v1/webhook-subscriptions/{id}/rotate-secret

Rotate the signing secret for a webhook subscription. The old secret will be immediately invalidated. This endpoint requires the X-IDEMPOTENCY-KEY header.

The subscription must be paused before rotating the secret. After rotating, you can resume the subscription to continue receiving notifications with the new secret.

Path Parameters

Name
id
Type
string
Required
Type
Description
The unique ID of the webhook subscription.

Request

POST

/v1/webhook-subscriptions/{id}/rotate-secret

  curl -X POST https://api.flowbrite.io/v1/webhook-subscriptions/{id}/rotate-secret \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}"

Responses

200 - OK

Example Responses

{
  "data": {
    "id": "whs_X01JTK7HABCDEF1234567890",
    "client": {
      "id": "cli_X01JTK7H3SZEEP3KVHA1ZFFRYDD",
      "name": "Joanna Bloggs Ltd"
    },
    "targetPlatform": "My App",
    "targetUrl": "https://example.com/webhooks/flowbrite",
    "events": ["payment.sent", "conversion.exchanged"],
    "isActive": true,
    "unsubscribedOn": null,
    "signingSecret": "whsec_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
    "auditHistory": null
  }
}

Resume

POST/v1/webhook-subscriptions/{id}/resume

Resume a paused webhook subscription. Notifications that were queued while the subscription was paused will be sent immediately upon resuming. This endpoint requires the X-IDEMPOTENCY-KEY header.

Path Parameters

Name
id
Type
string
Required
Type
Description
The unique ID of the webhook subscription.

Request

POST

/v1/webhook-subscriptions/{id}/resume

  curl -X POST https://api.flowbrite.io/v1/webhook-subscriptions/{id}/resume \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}"

Responses

200 - OK

Example Responses

{
  "data": {
    "id": "whs_X01JTK7HABCDEF1234567890",
    "isActive": true,
    "unsubscribedOn": null
  }
}

Unsubscribe

POST/v1/webhook-subscriptions/{id}/unsubscribe

Permanently unsubscribe from a webhook subscription. This action cannot be undone. This endpoint requires the X-IDEMPOTENCY-KEY header.

Path Parameters

Name
id
Type
string
Required
Type
Description
The unique ID of the webhook subscription.

Request

POST

/v1/webhook-subscriptions/{id}/unsubscribe

  curl -X POST https://api.flowbrite.io/v1/webhook-subscriptions/{id}/unsubscribe \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}"

Responses

200 - OK

Example Responses

{
  "data": {
    "id": "whs_X01JTK7HABCDEF1234567890",
    "isActive": false,
    "unsubscribedOn": "2025-06-05T14:00:00"
  }
}

Ping

POST/v1/webhook-subscriptions/{id}/ping

Send a test notification to a webhook subscription to verify connectivity. This endpoint requires the X-IDEMPOTENCY-KEY header.

Path Parameters

Name
id
Type
string
Required
Type
Description
The unique ID of the webhook subscription.

Request Body

Name
message
Type
string
Type
Description
An optional test message to include in the ping notification. Max 100 characters.

Request

POST

/v1/webhook-subscriptions/{id}/ping

  curl -X POST https://api.flowbrite.io/v1/webhook-subscriptions/{id}/ping \
  -H "X-API-KEY: {api_key}" \
  -H "X-IDEMPOTENCY-KEY: {idempotency_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello from Flowbrite!"
  }'

Responses

200 - OK

Example Responses

{
  "data": {
    "id": "whn_X01JTK7NABCDEF1234567890",
    "subscription": {
      "id": "whs_X01JTK7HABCDEF1234567890"
    },
    "eventType": "ping",
    "payload": {
      "message": "Hello from Flowbrite!"
    },
    "targetUrl": "https://example.com/webhooks/flowbrite",
    "createdOn": "2025-06-01T10:00:00",
    "sentOn": null,
    "attemptCount": 0,
    "lastError": null,
    "lockedUntil": null,
    "relatedEntityId": null,
    "relatedEntityType": null,
    "clonedFromNotificationId": null
  }
}