Webhooks | BeatAPI API Documentation

Create a webhook endpoint for optional BeatAPI task completion callbacks.

Store the signing secret returned at creation, verify every callback against the raw request body, and keep polling as the fallback source of truth. See the Quick Guide for production retry behavior.

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Request

This endpoint expects an object.

urlstringRequiredformat: "uri"

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

descriptionstringOptional

Optional internal label for identifying the endpoint in your account.

eventslist of enumsOptional

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

Allowed values:

Response

Webhook endpoint created

dataobject

Created or retrieved webhook endpoint. Public API responses return the full signing secret at creation and mask it afterward; authenticated dashboard owners can explicitly reveal it again.

Errors

400

Bad Request Error

401

Unauthorized Error

429

Too Many Requests Error

500

Internal Server Error

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

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	}