NewStripe: a buyer with a NIF always gets a standard invoice, and the simplified threshold is deprecated
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Webhook Subscriptions

Create a webhook subscription

Scopewebhooks:write

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

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

Header Parameters

Idempotency-Key?string

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.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Request Body

urlstring

HTTPS endpoint URL that will receive webhook POST requests.

Formaturi
eventsarray<WebhookEventTypeEnum>

List of event types to subscribe to.

Items1 <= items
account_relationship?string
Value in"own" | "managed" | "all"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

Callbacks

curl -X POST "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/webhooks" \  -H "Content-Type: application/json" \  -d '{    "url": "https://yourapp.com/webhooks/beel",    "events": [      "verifactu.status.updated"    ]  }'
{
  "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",
    "secret": "whsec_a3f5b2e1c9d8f7e6b5a4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2",
    "test_delivery": {
      "delivery_success": true,
      "http_status": 0,
      "duration_ms": 0,
      "error": "string",
      "failure_cause": "dns"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "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": "URL_TARGET_NOT_ALLOWED",
    "message": "The webhook URL points to an internal network address. Use an endpoint reachable from the internet."
  },
  "meta": {
    "timestamp": "2026-03-07T16:22:10Z",
    "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"
  }
}

List the webhook subscriptions GET

Returns the webhook subscriptions of the account in the path, active and inactive alike. Every member of the account sees the same list: who registered a subscription is authorship, not visibility. The signing secrets are never included.

Get a webhook subscription GET

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