Organization webhooks

Manage webhook endpoints across the organization from the Dashboard — configs, deliveries, and secret rotation.

These endpoints back the organization's webhooks screen: register endpoints, inspect deliveries and retries, and rotate signing secrets, across the org's merchants.

The signing secret (whsec_…) is shown only when created or rotated — capture it at that moment. Every delivery is signed; verify the X-Tokeflow-Signature before acting. See Verifying signatures.

These endpoints power the Tokeflow Dashboard UI at the organization level. They are session-authenticated (JWT bearer) — the token comes from signing in to the Dashboard, not from an sk_/pk_ API key. Requests also carry the x-organization-id header, and the signed-in user must be a member of that organization.

The webhook config object

Returned by the list and retrieve endpoints on this page.

Field	Type	Description
`id`	string	Unique identifier for the webhook configuration.
`merchant_id`	string	Merchant ID that owns this webhook configuration.
`url`	string	The URL where webhook events will be sent.
`description`	string \| null	Description for this webhook configuration.
`event_filter`	array \| null	List of event types subscribed to. Null means all events.
`is_active`	boolean	Whether this webhook configuration is active.
`created_at`	string	When the webhook configuration was created. (ISO 8601 UTC).
`updated_at`	string	When the webhook configuration was last updated. (ISO 8601 UTC).
`last_triggered_at`	string \| null	When the webhook was last triggered (most recent delivery). (ISO 8601 UTC).

Endpoints

GET`/api/v1/org/webhooks`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

List webhook configurations for merchant.

Query parameters

Field	Type	Required	Description
`page`	number	No	Page number (1-indexed). Default `1`, min `1`.
`limit`	number	No	Number of items per page. Default `20`, min `1`, max `100`.

Example request

curl -G https://api.tokeflow.com/api/v1/org/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Example response — 200

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
      "url": "https://api.example.com/webhooks/payments",
      "description": "Production payment notifications",
      "event_filter": [
        "transaction.authorized",
        "transaction.failed",
        "transaction.refunded"
      ],
      "is_active": true,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z",
      "last_triggered_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

POST`/api/v1/org/webhooks`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Create a new webhook configuration.

Request fields

Field	Type	Required	Description
`url`	string	Yes	The URL where webhook events will be sent.
`description`	string	No	Optional description for this webhook configuration.
`event_filter`	array	No	List of event types to subscribe to. If not provided, all events will be sent.

Example request

curl -X POST https://api.tokeflow.com/api/v1/org/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/payments",
    "description": "Production payment notifications",
    "event_filter": [
      "transaction.authorized",
      "transaction.failed",
      "transaction.refunded"
    ]
  }'

Example response — 201

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
  "url": "https://api.example.com/webhooks/payments",
  "description": "Production payment notifications",
  "event_filter": [
    "transaction.authorized",
    "transaction.failed",
    "transaction.refunded"
  ],
  "is_active": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "last_triggered_at": "2024-01-15T10:30:00.000Z",
  "secret": "whsec_abc123def456..."
}

GET`/api/v1/org/webhooks/deliveries`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

List all webhook deliveries for merchant.

Query parameters

Field	Type	Required	Description
`page`	number	No	Page number (1-indexed). Default `1`, min `1`.
`limit`	number	No	Number of items per page. Default `20`, min `1`, max `100`.
`status`	string	Yes	—

Example request

curl -G https://api.tokeflow.com/api/v1/org/webhooks/deliveries \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=active"

Example response — 200

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
      "merchant_webhook_config_id": "550e8400-e29b-41d4-a716-446655440002",
      "payment_transaction_id": "550e8400-e29b-41d4-a716-446655440003",
      "order_id": "550e8400-e29b-41d4-a716-446655440004",
      "event_type": "transaction.authorized",
      "payload": {
        "event": "transaction.authorized",
        "data": {
          "transaction_id": "..."
        }
      },
      "target_url": "https://api.example.com/webhooks/payments",
      "attempt_number": 1,
      "http_status_code": 200,
      "response_body": "{\"received\": true}",
      "status": "success",
      "next_retry_at": "2024-01-15T10:35:00.000Z",
      "created_at": "2024-01-15T10:30:00.000Z",
      "sent_at": "2024-01-15T10:30:01.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

GET`/api/v1/org/webhooks/webhook-deliveries/:delivery_id`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Get a specific webhook delivery.

Path parameters

Field	Type	Required	Description
`delivery_id`	string	Yes	—

Example request

curl https://api.tokeflow.com/api/v1/org/webhooks/webhook-deliveries/123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
  "merchant_webhook_config_id": "550e8400-e29b-41d4-a716-446655440002",
  "payment_transaction_id": "550e8400-e29b-41d4-a716-446655440003",
  "order_id": "550e8400-e29b-41d4-a716-446655440004",
  "event_type": "transaction.authorized",
  "payload": {
    "event": "transaction.authorized",
    "data": {
      "transaction_id": "..."
    }
  },
  "target_url": "https://api.example.com/webhooks/payments",
  "attempt_number": 1,
  "http_status_code": 200,
  "response_body": "{\"received\": true}",
  "status": "success",
  "next_retry_at": "2024-01-15T10:35:00.000Z",
  "created_at": "2024-01-15T10:30:00.000Z",
  "sent_at": "2024-01-15T10:30:01.000Z"
}

DELETE`/api/v1/org/webhooks/:webhook_id`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Delete a webhook configuration.

Path parameters

Field	Type	Required	Description
`webhook_id`	string	Yes	—

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 204 No Content

An empty body is returned on success.

GET`/api/v1/org/webhooks/:webhook_id`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Get webhook configuration by ID.

Path parameters

Field	Type	Required	Description
`webhook_id`	string	Yes	—

Example request

curl https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
  "url": "https://api.example.com/webhooks/payments",
  "description": "Production payment notifications",
  "event_filter": [
    "transaction.authorized",
    "transaction.failed",
    "transaction.refunded"
  ],
  "is_active": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "last_triggered_at": "2024-01-15T10:30:00.000Z"
}

PATCH`/api/v1/org/webhooks/:webhook_id`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Update a webhook configuration.

Path parameters

Field	Type	Required	Description
`webhook_id`	string	Yes	—

Request fields

Field	Type	Required	Description
`url`	string	No	The URL where webhook events will be sent.
`description`	string	No	Optional description for this webhook configuration.
`event_filter`	array	No	List of event types to subscribe to.
`is_active`	boolean	No	Whether this webhook configuration is active.

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/payments",
    "description": "Production payment notifications",
    "event_filter": [
      "transaction.authorized",
      "transaction.failed",
      "transaction.refunded"
    ],
    "is_active": true
  }'

Example response — 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
  "url": "https://api.example.com/webhooks/payments",
  "description": "Production payment notifications",
  "event_filter": [
    "transaction.authorized",
    "transaction.failed",
    "transaction.refunded"
  ],
  "is_active": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "last_triggered_at": "2024-01-15T10:30:00.000Z"
}

GET`/api/v1/org/webhooks/:webhook_id/deliveries`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

List webhook deliveries for a specific webhook.

Path parameters

Field	Type	Required	Description
`webhook_id`	string	Yes	—

Query parameters

Field	Type	Required	Description
`page`	number	No	Page number (1-indexed). Default `1`, min `1`.
`limit`	number	No	Number of items per page. Default `20`, min `1`, max `100`.
`status`	string	No	Filter by delivery status
`from`	string	No	From timestamp (ISO 8601 format) - filter deliveries after this time
`to`	string	No	To timestamp (ISO 8601 format) - filter deliveries before this time

Example request

curl -G https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42/deliveries \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=failed" \
  --data-urlencode "from=2024-01-01T00:00:00Z"

Example response — 200

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
      "merchant_webhook_config_id": "550e8400-e29b-41d4-a716-446655440002",
      "payment_transaction_id": "550e8400-e29b-41d4-a716-446655440003",
      "order_id": "550e8400-e29b-41d4-a716-446655440004",
      "event_type": "transaction.authorized",
      "payload": {
        "event": "transaction.authorized",
        "data": {
          "transaction_id": "..."
        }
      },
      "target_url": "https://api.example.com/webhooks/payments",
      "attempt_number": 1,
      "http_status_code": 200,
      "response_body": "{\"received\": true}",
      "status": "success",
      "next_retry_at": "2024-01-15T10:35:00.000Z",
      "created_at": "2024-01-15T10:30:00.000Z",
      "sent_at": "2024-01-15T10:30:01.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

POST`/api/v1/org/webhooks/:webhook_id/rotate-secret`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Rotate the webhook secret.

Path parameters

Field	Type	Required	Description
`webhook_id`	string	Yes	—

Example request

curl -X POST https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42/rotate-secret \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
  "url": "https://api.example.com/webhooks/payments",
  "description": "Production payment notifications",
  "event_filter": [
    "transaction.authorized",
    "transaction.failed",
    "transaction.refunded"
  ],
  "is_active": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "last_triggered_at": "2024-01-15T10:30:00.000Z",
  "secret": "whsec_abc123def456..."
}

POST`/api/v1/org/webhooks/:webhook_id/test`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Test a webhook configuration by sending a test event.

Path parameters

Field	Type	Required	Description
`webhook_id`	string	Yes	—

Example request

curl -X POST https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 200

{
  "success": true,
  "message": "Operation completed successfully",
  "http_status": 200
}

Errors

Errors use the standard envelope. The most common cases here:

HTTP	Meaning
`400`	Invalid parameters or a state that does not allow this operation.
`401`	Missing, expired, or invalid Dashboard session token.
`403`	Authenticated, but the signed-in user lacks access to this entity.
`404`	The record does not exist or is not visible to this entity.

Organization webhooks

The webhook config object

Endpoints

GET/api/v1/org/webhooks

POST/api/v1/org/webhooks

GET/api/v1/org/webhooks/deliveries

GET/api/v1/org/webhooks/webhook-deliveries/:delivery_id

DELETE/api/v1/org/webhooks/:webhook_id

GET/api/v1/org/webhooks/:webhook_id

PATCH/api/v1/org/webhooks/:webhook_id

GET/api/v1/org/webhooks/:webhook_id/deliveries

POST/api/v1/org/webhooks/:webhook_id/rotate-secret

POST/api/v1/org/webhooks/:webhook_id/test

Errors

Related

On this page

GET`/api/v1/org/webhooks`

POST`/api/v1/org/webhooks`

GET`/api/v1/org/webhooks/deliveries`

GET`/api/v1/org/webhooks/webhook-deliveries/:delivery_id`

DELETE`/api/v1/org/webhooks/:webhook_id`

GET`/api/v1/org/webhooks/:webhook_id`

PATCH`/api/v1/org/webhooks/:webhook_id`

GET`/api/v1/org/webhooks/:webhook_id/deliveries`

POST`/api/v1/org/webhooks/:webhook_id/rotate-secret`

POST`/api/v1/org/webhooks/:webhook_id/test`