---
title: "Register Webhook"
method: POST
path: "/api/v1/webhooks/register"
tags: ["webhooks"]
---

# Register Webhook

`POST /api/v1/webhooks/register`

## Request

- Base URL: `https://api.bellatorsi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.bellatorsi.com/api/v1/webhooks/register`
- Auth: none declared

Register webhook callback URL for async job notifications.

**Webhook Events:**
- `job.completed` - Job finished successfully
- `job.failed` - Job encountered error
- `job.cancelled` - Job was cancelled

**Webhook Payload:**
```json
{
    "event": "job.completed",
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-01-08T12:00:25Z",
    "data": {
        "job_id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "completed",
        "result": {...}
    }
}
```

**Signature Verification:**
- HMAC-SHA256 signature in `X-Bellator-Signature` header
- Format: `sha256=<hex_signature>`
- Payload: JSON-serialized webhook payload (deterministic order)

**Delivery Guarantees:**
- At-least-once delivery
- Max 3 retry attempts with exponential backoff
- 5 second initial retry delay, 15 second max delay
- Target delivery: <5 seconds after job completion

**Best Practices:**
- Return 2xx status code quickly (<1 second)
- Process webhook payload asynchronously
- Verify signature if secret provided
- Implement idempotency using job_id

## Headers

- `x-api-key` string, nullable
- `authorization` string, nullable
- `x-bellator-internal-dispatch` string, nullable

## Request body

- WebhookRegistration: Model for webhook callback registration.
  - `url` string, uri, required: Webhook callback URL
  - `events` string[]: Events to trigger webhook
  - `secret` string, nullable: Shared secret for webhook signature validation

## Response `200`

Success - Webhook registered

- object

## Other responses

- `400`: Bad Request - Invalid webhook configuration
- `422`: Validation Error
- `429`: Too Many Requests - Rate limit exceeded

---

[API](https://skmtc.dev/bellatorsi/apis/bellator-schedule-intelligence-apis.md) · [All operations](https://skmtc.dev/bellatorsi/apis/bellator-schedule-intelligence-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/bellatorsi/apis/bellator-schedule-intelligence-apis/revisions/03e7b786e43b?raw)