Retry a failed webhook delivery
Scopewebhooks:writeRe-sends the original payload of a delivery immediately.
- Payload: the one captured when the event happened, not a fresh snapshot, so changes made to the entity since then are not reflected.
- History: the outcome is recorded as a new entry and the original entry is kept
as it was.
attempt_numbercontinues the same sequence, so it can exceed the number of automatic attempts.
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
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.
uuidSubscription 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.
uuidDelivery attempt of that subscription to replay.
uuidHeader Parameters
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.
| Status | Code | When |
|---|---|---|
400 | INVALID_IDEMPOTENCY_KEY | The key breaks the format rules above. |
409 | IDEMPOTENCY_KEY_PROCESSING | The first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key. |
409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
^[a-zA-Z0-9_-]+$length <= 255Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08/deliveries/497f6eca-6276-4993-bfeb-53cbbbba6f08/retry"{
"success": true,
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627",
"webhook_event_id": "de12c964-92b7-4192-bb5b-e637b567397c",
"event_type": "verifactu.status.updated",
"attempt_number": 0,
"http_status": 200,
"response_body": "string",
"response_body_truncated": true,
"response_body_length": 29094,
"duration_ms": 0,
"success": true,
"error_message": "string",
"payload": "string",
"request_headers": {
"BeeL-Signature": "t=1741362026,v1=3c4f7a2e1b9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f",
"BeeL-Event": "verifactu.status.updated",
"BeeL-Event-Id": "8ee6b023-c4e5-482e-93ca-dc66da2f9cb5",
"BeeL-Delivery-Id": "b3873959-67d8-4a11-87ba-b39cc2d395fe",
"Idempotency-Key": "8ee6b023-c4e5-482e-93ca-dc66da2f9cb5"
},
"delivered_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": "INVOICE_NOT_FOUND",
"message": "Invoice 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"
}
}List the delivery attempts of a webhook GET
Returns the delivery attempts of this subscription, newest first. Each entry records one attempt with the response it got, so a retried event appears once per attempt. - **`event_type`:** narrows the list to a single event type. - **`event_id`:** follows one event across every attempt made on it, without paging through the whole history.
Create a webhook subscription (deprecated) POST
**Deprecated.** Use `POST /v1/accounts/{account_id}/webhooks`, which behaves identically. 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. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.