Create a webhook endpoint

The signing secret is returned only once at creation time. Store it
securely. Later responses return a masked secret.

BeatAPI sends these headers with each delivery:

x-beatapi-event: task.succeeded or task.failed

x-beatapi-timestamp: Unix timestamp in seconds

x-beatapi-signature: hex HMAC-SHA256 signature

Verify the signature by computing:
hmac_sha256(secret, timestamp + "." + raw_request_body).

Example delivery body:

{
  "id": "evt_123",
  "event": "task.succeeded",
  "created_at": 1782210300,
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "workflow": "music-video",
    "status": "succeeded",
    "stage": "succeeded",
    "storyboard": {
      "shots": [
        {
          "id": "shot_xxx",
          "index": 0,
          "status": "succeeded",
          "duration_seconds": 5,
          "prompt": "Opening lyric shot.",
          "lyric_text": "Intro",
          "created_at": 1782210000,
          "updated_at": 1782210300
        }
      ]
    },
    "created_at": 1782210000,
    "updated_at": 1782210300,
    "completed_at": 1782210300,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_8K2qA/0.mp4",
          "mime_type": "video/mp4"
        }
      ]
    },
    "usage": {
      "credits_reserved": 76,
      "credits_charged": 76,
      "billable_duration_seconds": 15,
      "credits_settled": 76,
      "credits_refunded": 0
    },
    "request_id": "req_abc123",
    "error_code": null,
    "error_message": null
  }
}

Reject old timestamps to prevent replay attacks. A 5 minute window is
recommended. Failed deliveries are retried at most 3 times with fixed
backoff windows of 1 minute, 5 minutes, and 15 minutes. Polling
GET /v1/tasks/{task_id} remains the source of truth.

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location 'https://api.beatapi.io/v1/webhooks' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://example.com/beatapi-webhook", "events": [ "task.succeeded", "task.failed" ] }'

{ "data": { "id": "wh_9aBcD", "object": "webhook_endpoint", "url": "https://example.com/beatapi-webhook", "description": "Production webhook", "events": [ "task.succeeded", "task.failed" ], "status": "active", "secret": "whsec_example_store_this_once", "created_at": 1782210000, "updated_at": 1782210000 } }

Create a webhook endpoint

Request

Responses