Skip to main content
FlownallyAPI Docs

Webhooks

LLM
View as Markdown
Open llms.txt

Configure signed webhook deliveries for contacts, conversations, and messages.

8 generated endpoints in this resource group.

get/webhooks

Get webhook settings#

Returns the current tenant webhook configuration, selected event types, and event types that can be subscribed to.

Authorization

Scheme

  • bearerAuth

Required scopes

  • webhook:read

Allowed roles

  • owner
  • admin

Read webhook settings.

Responses

  • Name
    200
    Type
    application/json
    Description
    Webhook settings
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

GETRequest
curl -X GET "https://api.flownally.com/v1/webhooks" \
  -H "Authorization: Bearer {token}"

Response

200application/json
{
  "id": "string",
  "enabled": true,
  "verified": true,
  "url": "https://example.com",
  "eventTypes": [
    "contact.created"
  ],
  "availableEventTypes": [
    "contact.created"
  ],
  "createdAt": "2026-04-27T00:00:00.000Z",
  "updatedAt": "2026-04-27T00:00:00.000Z"
}
patch/webhooks

Update webhook settings#

Partially updates the single webhook configuration for the current tenant. Select event types from availableEventTypes.

Authorization

Scheme

  • bearerAuth

Required scopes

  • webhook:update

Allowed roles

  • owner
  • admin

Update webhook settings.

Request body

Send a application/json body. The body is required for this operation.

Optional attributes

  • Name
    enabled
    Type
    boolean
    Description
    Optional request attribute.
  • Name
    url
    Type
    string
    Description
    Optional request attribute.
  • Name
    eventTypes
    Type
    array<WebhookEventType>
    Description
    Optional request attribute.

Responses

  • Name
    200
    Type
    application/json
    Description
    Updated webhook settings
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

PATCHRequest
curl -X PATCH "https://api.flownally.com/v1/webhooks" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "url": "https://example.com",
  "eventTypes": [
    "contact.created"
  ]
}'

Response

200application/json
{
  "id": "string",
  "enabled": true,
  "verified": true,
  "url": "https://example.com",
  "eventTypes": [
    "contact.created"
  ],
  "availableEventTypes": [
    "contact.created"
  ],
  "createdAt": "2026-04-27T00:00:00.000Z",
  "updatedAt": "2026-04-27T00:00:00.000Z"
}
delete/webhooks

Delete webhook settings#

Disables and removes the current tenant webhook configuration. Attempt logs remain visible for the retention window.

Authorization

Scheme

  • bearerAuth

Required scopes

  • webhook:delete

Allowed roles

  • owner
  • admin

Delete webhook settings.

Responses

  • Name
    204
    Description
    Webhook settings deleted
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

DELETERequest
curl -X DELETE "https://api.flownally.com/v1/webhooks" \
  -H "Authorization: Bearer {token}"

Response

204
204 Webhook settings deleted
post/webhooks/verify

Verify webhook delivery#

Sends a signed synthetic webhook test event to the supplied URL or the saved webhook URL.

Authorization

Scheme

  • bearerAuth

Required scopes

  • webhook:update

Allowed roles

  • owner
  • admin

Verify webhook delivery.

Request body

Send a application/json body. The body is optional for this operation.

Optional attributes

  • Name
    url
    Type
    string
    Description
    Optional request attribute.

Responses

  • Name
    200
    Type
    application/json
    Description
    Verification result
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

POSTRequest
curl -X POST "https://api.flownally.com/v1/webhooks/verify" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com"
}'

Response

200application/json
{
  "delivered": true,
  "statusCode": 0,
  "error": "string"
}
get/webhooks/attempts

List webhook delivery attempts#

Returns newest-first webhook delivery attempts from the last 7 days. Use this for delivery debugging, not long-term audit.

Authorization

Scheme

  • bearerAuth

Required scopes

  • webhook:read

Allowed roles

  • owner
  • admin

List webhook delivery attempts.

Optional parameters

  • Name
    limit
    Type
    query integer
    Description
    Optional parameter.
  • Name
    pageToken
    Type
    query string
    Description
    Optional parameter.
  • Name
    eventType
    Type
    query WebhookEventName
    Description
    Optional parameter.
  • Name
    status
    Type
    query WebhookAttemptStatus
    Description
    Optional parameter.

Responses

  • Name
    200
    Type
    application/json
    Description
    Webhook delivery attempts
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

GETRequest
curl -G "https://api.flownally.com/v1/webhooks/attempts" \
  -H "Authorization: Bearer {token}" \
  -d limit="{limit}" \
  -d pageToken="{pageToken}" \
  -d eventType="{eventType}" \
  -d status="{status}"

Response

200application/json
{
  "attempts": [
    {
      "id": "string",
      "eventId": "string",
      "eventType": {},
      "status": "succeeded",
      "deliveryId": "string",
      "attemptNumber": 0,
      "attemptedAt": "2026-04-27T00:00:00.000Z",
      "responseStatus": 0,
      "responseBody": "string",
      "latencyMs": 0,
      "errorText": "string",
      "signedWithVersions": [
        0
      ]
    }
  ],
  "nextPageToken": "string"
}
get/webhooks/signing-keys

List webhook signing keys for the current tenant#

Returns the active and any expiring (mid-rotation) webhook signing keys. On the very first call for a tenant, a key is bootstrapped automatically and its plaintext is included in the response — exactly once. Subsequent calls return metadata only (no plaintext).

Authorization

Scheme

  • bearerAuth

Required scopes

  • webhook:read

Allowed roles

  • owner
  • admin

List webhook signing keys.

Responses

  • Name
    200
    Type
    application/json
    Description
    List of signing keys (plaintext present only on bootstrap response)
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

GETRequest
curl -X GET "https://api.flownally.com/v1/webhooks/signing-keys" \
  -H "Authorization: Bearer {token}"

Response

200application/json
{
  "keys": [
    {
      "id": "string",
      "version": 0,
      "status": "string",
      "createdAt": "2026-04-27T00:00:00.000Z",
      "expiresAt": "2026-04-27T00:00:00.000Z",
      "last4": "string",
      "plaintextKey": "string"
    }
  ]
}
post/webhooks/signing-keys/rotate

Rotate the webhook signing key#

Generates a new signing key for webhook deliveries and demotes the previous active key to "expiring" with a 24h overlap. During the overlap, both keys are valid signers; receivers can update at their own pace. Returns the plaintext of the newly-generated key exactly once.

Authorization

Scheme

  • bearerAuth

Required scopes

  • webhook:update

Allowed roles

  • owner
  • admin

Rotate a webhook signing key.

Responses

  • Name
    200
    Type
    application/json
    Description
    New key generated; plaintext returned exactly once
  • Name
    default
    Type
    application/json
    Description
    Error

Related schemas

Request

POSTRequest
curl -X POST "https://api.flownally.com/v1/webhooks/signing-keys/rotate" \
  -H "Authorization: Bearer {token}"

Response

200application/json
{
  "key": {
    "id": "string",
    "version": 0,
    "status": "string",
    "createdAt": "2026-04-27T00:00:00.000Z",
    "expiresAt": "2026-04-27T00:00:00.000Z",
    "last4": "string",
    "plaintextKey": "string"
  }
}
post{configured webhook URL}

Webhook payloads#

Endpoint shape implemented by external webhook receivers. Return any 2xx response after accepting an event.

Authorization

Scheme

  • standardWebhooks

External receiver endpoint shape for webhook events.

Required parameters

  • Name
    webhook-id
    Type
    header string
    Description
    Stable event identifier. Deduplicate deliveries with this value.
  • Name
    webhook-timestamp
    Type
    header integer
    Description
    Unix timestamp in seconds for the delivery attempt. Reject stale timestamps to prevent replay.
  • Name
    webhook-signature
    Type
    header string
    Description
    Standard Webhooks signature header. Verify it against `webhook-id`, `webhook-timestamp`, and the exact raw request body.

Request body

Flownally sends a application/json body. The body is required for this operation.

Payload variants

  • Name
    contact.created
    Type
    ContactCreatedWebhookEvent
    Description
  • Name
    contact.updated
    Type
    ContactUpdatedWebhookEvent
    Description
  • Name
    contact.archived
    Type
    ContactArchivedWebhookEvent
    Description
  • Name
    conversation.started
    Type
    ConversationStartedWebhookEvent
    Description
  • Name
    conversation.updated
    Type
    ConversationUpdatedWebhookEvent
    Description
  • Name
    conversation.closed
    Type
    ConversationClosedWebhookEvent
    Description
  • Name
    message.created
    Type
    MessageCreatedWebhookEvent
    Description
  • Name
    message.updated
    Type
    MessageUpdatedWebhookEvent
    Description

Responses

  • Name
    2XX
    Description
    Event accepted

Payload

{
  "id": "string",
  "type": "contact.created",
  "timestamp": "string",
  "data": {
    "contact": {
      "id": "con_01HV8Y5R5RFMS0TFK6PKF9H2S8",
      "tenantId": "tn_01HV8Y1N3QPY9X2HBQ1M9E8D0",
      "name": "Anna Kowalska",
      "createdAt": "2026-04-30T09:20:00Z",
      "updatedAt": "2026-04-30T10:10:00Z",
      "identities": [
        {
          "id": "idn_01HV8Y7YF5J4Y7M9M7T3H3X2A1",
          "channel": "whatsapp",
          "metadata": {
            "phoneNumber": "+48123456789"
          }
        }
      ],
      "tagIds": [
        "tag_01HV8Y9R3Q4J6A7M8N9P0Q2S4"
      ],
      "customFields": {
        "lifecycleStage": "customer",
        "preferredStore": "Krakow"
      },
      "archivedAt": null
    }
  }
}

Response

2XX
2XX Event accepted