AccountWebhooks

Create a webhook subscription

Registers an HTTPS endpoint to receive notifications for the event types listed in events.

  • secret: returned only in this response and never again. Store it before discarding the body; deliveries are signed with it and carry the signature in the BeeL-Signature header.
  • test_delivery: a one-off signed delivery sent to your URL as part of creating the subscription, so you learn whether your endpoint answers without a second call. It is best effort: the subscription exists and is active whatever it says, and the field is null when the test could not be run at all.
  • account_relationship: which accounts the subscription receives events from — own (the default), managed, or all.
  • Limits: an account holds at most 10 active subscriptions; creating an eleventh is rejected with 400 WEBHOOK_ACTIVE_SUBSCRIPTION_LIMIT_REACHED. Registering the same URL twice creates two subscriptions, and the endpoint then receives each event twice.
post/v1/accounts/{account_id}/webhooks

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/accounts/{account_id}/webhooks
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

urlstring uri required

HTTPS endpoint URL that will receive webhook POST requests.

eventsWebhookEventTypeEnum[] required

List of event types to subscribe to.

account_relationship'own' | 'managed' | 'all'

Which accounts a subscription receives events from — the same vocabulary as the account_relationship field in every delivered event envelope. One term to ask for events, the same term to route them on arrival.

  • own (default) — only your own account.
  • managed — only accounts you manage (accounts you provisioned). Whether you actually receive them also depends on the management relationship granting data visibility; a billing-only relationship does not.
  • all — both.

A delivered event is always own or managed (never all): its account_relationship, alongside account_id and account_external_ref, tells you which account it belongs to.

Example request

{
  "url": "https://yourapp.com/webhooks/beel",
  "events": [
    "invoice.issued",
    "verifactu.status.updated"
  ]
}

Response

Webhook subscription created

successboolean required

Example response

{
  "success": true,
  "data": {
    "secret": "whsec_a3f5b2e1c9d8f7e6b5a4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.