NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Webhook Subscriptions

Get a webhook subscription

Scopewebhooks:read

Returns a single webhook subscription. The signing secret is never included.

GET
/v1/accounts/{account_id}/webhooks/{webhook_id}

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Path Parameters

account_idstring

Your own account, or an account you provisioned. It — not the credential, and not the BeeL-Active-Company header — decides which account the operation acts on. An account you do not reach answers 403, and so does an account that does not exist, so the existence of somebody else's account is never disclosed.

Formatuuid
webhook_idstring

Subscription of the account in the path. A subscription of another account answers 404, the same as one that does not exist: under the account resolved from {account_id} it simply is not there.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "url": "http://example.com",
    "events": [
      "string"
    ],
    "active": true,
    "account_relationship": "own",
    "deactivated_by": "owner",
    "deactivated_at": "2019-08-24T14:15:22Z",
    "last_error": "string",
    "last_error_cause": "dns",
    "consecutive_failures": 0,
    "last_used_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Create a webhook subscription POST

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. Registering the same URL twice creates two subscriptions, and the endpoint then receives each event twice.

Update a webhook subscription PATCH

Updates the fields present in the body — `url`, `events`, `active`, `account_relationship` — and leaves the rest untouched. - **`events`:** replaces the whole list, it does not add to it, so an event left out of it stops being delivered. - **`active`:** setting it to `false` stops deliveries without discarding the delivery history. A subscription we turned off ourselves (`deactivated_by: beel`) needs a successful test delivery before it can be turned back on. - **Signing secret:** not touched here. Rotate it with `POST /v1/accounts/{account_id}/webhooks/{webhook_id}/secret`.