Webhooks

POST https://api.beatapi.io/v1/webhooks

Create a webhook endpoint for optional BeatAPI task completion callbacks.

Authorization

Authorization   string   required

Send your BeatAPI API key as a Bearer token. Create one on the Dashboard.

Authorization: Bearer <BEATAPI_API_KEY>

Keep permanent API keys on trusted servers. Content-Type: application/json is required for the request body. Idempotency-Key is optional when the endpoint exposes it and is recommended for safe retries with the exact same body.

Request body

url   string   required

Public HTTPS callback URL that accepts BeatAPI task events. Do not use localhost or a private-network URL.

Format: uri

description   string   optional

Optional internal label for identifying the endpoint in your account.

events   string[]   optional

Task events to deliver. Omit to subscribe to both task.succeeded and task.failed.

Response

A successful request returns HTTP 201.

1
{
2
  "data": {
3
    "id": "wh_9aBcD",
4
    "object": "webhook_endpoint",
5
    "url": "https://example.com/beatapi-webhook",
6
    "description": "Production webhook",
7
    "events": [
8
      "task.succeeded",
9
      "task.failed"
10
    ],
11
    "status": "active",
12
    "secret": "whsec_example_store_this_once",
13
    "created_at": 1782210000,
14
    "updated_at": 1782210000
15
  }
16
}

Verify callback signatures

BeatAPI sends x-beatapi-event, x-beatapi-timestamp, and x-beatapi-signature with every delivery. Compute the expected hex HMAC-SHA256 value over:

timestamp + "." + raw_request_body

Use the endpoint secret returned by this create request. Compare signatures in constant time, verify the exact raw bytes before JSON parsing, and reject timestamps older than 5 minutes to limit replay attacks.

Manage endpoints

• GET /v1/webhooks lists webhook endpoints.
• GET /v1/webhooks/{id} gets a webhook endpoint.
• PATCH /v1/webhooks/{id} updates a webhook endpoint.
• DELETE /v1/webhooks/{id} deletes a webhook endpoint.

Next step

Verify every callback signature before parsing its payload. Polling GET /v1/tasks/{task_id} remains the source of truth if delivery is delayed or fails.

Errors