Webhooks - ELAN AI Bridge API

Webhooks allow you to receive real-time HTTP notifications when events occur in your organization. Instead of polling the API, you can subscribe to specific events and receive push notifications to your server.

Available event types

The following event types are available for webhook subscriptions:

workflow.started - A workflow has started execution
workflow.completed - A workflow has completed successfully
workflow.failed - A workflow has failed
workflow.step.started - A workflow step has started
workflow.step.completed - A workflow step has completed
workflow.step.failed - A workflow step has failed

Webhook payload

When an event occurs, your webhook URL will receive a POST request with the following payload structure:

{
  "event_id": "evt_abc123",
  "event_type": "workflow.completed",
  "workflow_id": "wf_xyz789",
  "organization_id": "org_123",
  "timestamp": "2025-12-21T10:30:00Z",
  "data": {
    // Event-specific data
  }
}

Security

If you provide a secret when creating a webhook, all requests will include an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body. Verify this signature to ensure requests are authentic.

The webhook subscription model

The webhook subscription model contains information about a webhook configuration.

Properties

integer

Unique identifier for the webhook subscription.

name

string

Human-readable name for the webhook.

url

string

The target URL where webhook payloads will be delivered.

events

array

List of event types this webhook is subscribed to.

is_active

boolean

Whether the webhook is currently active.

created_at

timestamp

When the webhook subscription was created.

updated_at

timestamp

When the webhook subscription was last updated.

Create webhook subscription

POST /webhooks This endpoint allows you to create a new webhook subscription for your organization.

Required attributes

name

string

required

A human-readable name for the webhook (max 255 characters).

url

string

required

The target URL for webhook delivery (max 2048 characters). Must be HTTPS.

events

array

required

List of event types to subscribe to.

Optional attributes

secret

string

A secret key for HMAC-SHA256 signature verification (max 255 characters).

headers

object

Custom headers to include in webhook requests.

X-Org-Id

string

Organization identifier (header). If not provided, uses your default organization.

curl -X POST https://api.elanlanguages.ai/v1/webhooks \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Webhook",
    "url": "https://api.example.com/webhooks/elan",
    "events": ["workflow.completed", "workflow.failed"],
    "secret": "your-webhook-secret",
    "headers": {
      "X-Custom-Header": "custom-value"
    }
  }'

Response

{
  "id": 1,
  "name": "Production Webhook",
  "url": "https://api.example.com/webhooks/elan",
  "events": ["workflow.completed", "workflow.failed"],
  "is_active": true,
  "created_at": "2025-12-21T10:30:00Z",
  "updated_at": null
}

List webhook subscriptions

GET /webhooks This endpoint returns all webhook subscriptions for your organization.

Optional attributes

X-Org-Id

string

Organization identifier (header). If not provided, uses your default organization.

curl https://api.elanlanguages.ai/v1/webhooks \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}"

Response

{
  "subscriptions": [
    {
      "id": 1,
      "name": "Production Webhook",
      "url": "https://api.example.com/webhooks/elan",
      "events": ["workflow.completed", "workflow.failed"],
      "is_active": true,
      "created_at": "2025-12-21T10:30:00Z",
      "updated_at": null
    }
  ],
  "total": 1
}

Get webhook subscription

GET /webhooks/:subscription_id This endpoint returns details of a specific webhook subscription.

Required attributes

subscription_id

integer

required

The unique identifier for the webhook subscription.

Optional attributes

X-Org-Id

string

Organization identifier (header). If not provided, uses your default organization.

curl https://api.elanlanguages.ai/v1/webhooks/1 \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}"

Response

{
  "id": 1,
  "name": "Production Webhook",
  "url": "https://api.example.com/webhooks/elan",
  "events": ["workflow.completed", "workflow.failed"],
  "is_active": true,
  "created_at": "2025-12-21T10:30:00Z",
  "updated_at": null
}

Update webhook subscription

PATCH /webhooks/:subscription_id This endpoint allows you to update an existing webhook subscription. All fields are optional - only provided fields will be updated.

Required attributes

subscription_id

integer

required

The unique identifier for the webhook subscription.

Optional attributes

name

string

A new name for the webhook.

url

string

A new target URL for webhook delivery.

events

array

Updated list of event types to subscribe to.

secret

string

A new secret key for signature verification.

headers

object

Updated custom headers.

is_active

boolean

Enable or disable the webhook.

X-Org-Id

string

Organization identifier (header). If not provided, uses your default organization.

curl -X PATCH https://api.elanlanguages.ai/v1/webhooks/1 \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["workflow.completed", "workflow.failed", "workflow.started"],
    "is_active": true
  }'

Response

{
  "id": 1,
  "name": "Production Webhook",
  "url": "https://api.example.com/webhooks/elan",
  "events": ["workflow.completed", "workflow.failed", "workflow.started"],
  "is_active": true,
  "created_at": "2025-12-21T10:30:00Z",
  "updated_at": "2025-12-21T11:00:00Z"
}

Delete webhook subscription

DELETE /webhooks/:subscription_id This endpoint deletes a webhook subscription. This action cannot be undone.

Required attributes

subscription_id

integer

required

The unique identifier for the webhook subscription to delete.

Optional attributes

X-Org-Id

string

Organization identifier (header). If not provided, uses your default organization.

curl -X DELETE https://api.elanlanguages.ai/v1/webhooks/1 \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}"

Response

// Returns 204 No Content on success

List webhook delivery logs

GET /webhooks/:subscription_id/logs This endpoint returns delivery logs for a specific webhook subscription, showing all delivery attempts including retries.

Required attributes

subscription_id

integer

required

The unique identifier for the webhook subscription.

Optional attributes

limit

integer

Maximum number of logs to return (default: 50).

offset

integer

Number of logs to skip for pagination (default: 0).

X-Org-Id

string

Organization identifier (header). If not provided, uses your default organization.

curl -G https://api.elanlanguages.ai/v1/webhooks/1/logs \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}" \
  -d limit=10

Response

{
  "logs": [
    {
      "id": 100,
      "webhook_id": 1,
      "webhook_type": "subscription",
      "event_type": "workflow.completed",
      "event_id": "evt_abc123",
      "target_url": "https://api.example.com/webhooks/elan",
      "status": "delivered",
      "attempts": 1,
      "response_status": 200,
      "error_message": null,
      "created_at": "2025-12-21T10:30:00Z",
      "last_attempt_at": "2025-12-21T10:30:01Z"
    }
  ],
  "total": 45
}

List all delivery logs

GET /webhooks/logs/all This endpoint returns all webhook delivery logs for your organization, optionally filtered by event type.

Optional attributes

event_type

string

Filter logs by event type.

limit

integer

Maximum number of logs to return (default: 50).

offset

integer

Number of logs to skip for pagination (default: 0).

X-Org-Id

string

Organization identifier (header). If not provided, uses your default organization.

curl -G https://api.elanlanguages.ai/v1/webhooks/logs/all \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}" \
  -d event_type=workflow.completed \
  -d limit=10

Response

{
  "logs": [
    {
      "id": 100,
      "webhook_id": 1,
      "webhook_type": "subscription",
      "event_type": "workflow.completed",
      "event_id": "evt_abc123",
      "target_url": "https://api.example.com/webhooks/elan",
      "status": "delivered",
      "attempts": 1,
      "response_status": 200,
      "error_message": null,
      "created_at": "2025-12-21T10:30:00Z",
      "last_attempt_at": "2025-12-21T10:30:01Z"
    }
  ],
  "total": 120
}

Test webhook

POST /webhooks/:subscription_id/test This endpoint sends a test event to a webhook subscription to verify your configuration. A test workflow.completed event will be sent, and the delivery will appear in the subscription’s logs.

Required attributes

subscription_id

integer

required

The unique identifier for the webhook subscription to test.

Optional attributes

X-Org-Id

string

Organization identifier (header). If not provided, uses your default organization.

curl -X POST https://api.elanlanguages.ai/v1/webhooks/1/test \
  -H "Authorization: Bearer {token}" \
  -H "X-Org-Id: {orgId}"

Response

{
  "message": "Test webhook sent successfully",
  "event_id": "evt_test_xyz789"
}

​Available event types

​Webhook payload

​Security

​The webhook subscription model

​Properties

​Create webhook subscription

​Required attributes

​Optional attributes

​List webhook subscriptions

​Optional attributes

​Get webhook subscription

​Required attributes

​Optional attributes

​Update webhook subscription

​Required attributes

​Optional attributes

​Delete webhook subscription

​Required attributes

​Optional attributes

​List webhook delivery logs

​Required attributes

​Optional attributes

​List all delivery logs

​Optional attributes

​Test webhook

​Required attributes

​Optional attributes

Available event types

Webhook payload

Security

The webhook subscription model

Properties

Create webhook subscription

Required attributes

Optional attributes

List webhook subscriptions

Optional attributes

Get webhook subscription

Required attributes

Optional attributes

Update webhook subscription

Required attributes

Optional attributes

Delete webhook subscription

Required attributes

Optional attributes

List webhook delivery logs

Required attributes

Optional attributes

List all delivery logs

Optional attributes

Test webhook

Required attributes

Optional attributes