Rotate the signing secret of a webhook
Scopewebhooks:writeDeprecated. Use POST /v1/accounts/{account_id}/webhooks/{webhook_id}/secret, which behaves identically.
Generates a new HMAC signing secret for a webhook subscription.
- Old secret: immediately invalidated. Update your signature verification logic before rotating, to avoid missing events during the transition.
- New secret: returned once, in this response only. It cannot be read again.
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
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) - If the same key is sent twice, the result of the first operation is returned
- Keys 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 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
curl -X POST "https://app.beel.es/api/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08/secret"{
"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": "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": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type: text/plain. Supported: application/json"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Send a test event to a webhook endpoint POST
**Deprecated.** Use `POST /v1/accounts/{account_id}/webhooks/{webhook_id}/test`, which behaves identically. Sends a synthetic payload to the subscription's URL immediately, outside the normal delivery queue. Use it to verify that your endpoint is reachable and handles deliveries correctly before you rely on real events. - **Payload:** carries `"test": true` and synthetic data, and is signed like any other delivery, so it also exercises your signature check. - **Retries:** none. A failed test is not retried and does not appear in the delivery history. - **`Idempotency-Key`:** repeating the call with the same key returns the cached result without sending the test payload again. - **Result:** read `delivery_success`; a delivery your endpoint rejected is still a successful test run, not an error.
List the delivery attempts of a webhook GET
**Deprecated.** Use `GET /v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries`, which behaves identically. 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.