POST/api/v1/webhooks/register

Register Webhook

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:

{
    "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

Request example

json
json
{
  "tasks": [
    {
      "id": "T1",
      "duration_days": 5
    }
  ]
}

Request fields from OpenAPI contract

This table is generated from the endpoint schema in openapi.json.

FieldTypeRequiredDescription
urlstringRequiredWebhook callback URL
eventsarray<string>OptionalEvents to trigger webhook
secretstring | nullOptionalShared secret for webhook signature validation

Response example

json
json
{
  "status": "registered",
  "webhook_id": "wh_abc123",
  "url": "https://customer.example.com/webhooks/bellator",
  "events": [
    "job.completed",
    "job.failed"
  ],
  "message": "Webhook registered successfully. Will be used for all async jobs."
}

Schema

json-schema
{
  "type": "object",
  "additionalProperties": {
    "anyOf": [
      {
        "type": "string"
      },
      {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    ]
  },
  "title": "Response Register Webhook Api V1 Webhooks Register Post"
}

Authentication

  • x-api-key header

Reference details

Operation ID
register_webhook_api_v1_webhooks_register_post
Section
webhooks
Tags
webhooks

Was this page helpful?

Your feedback helps us improve docs, reference pages, and Playground flows.

Topic: Register Webhook · Page: /docs/api-reference/register_webhook_api_v1_webhooks_register_post

Report an issueSuggest improvement

TermsPrivacyContact

Schedule analysis guidance. Not legal advice. You remain responsible for contract and agency compliance.