Webhooks

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

Name
id
Type
integer
Description
Unique identifier for the webhook subscription.
Name
name
Type
string
Description
Human-readable name for the webhook.
Name
url
Type
string
Description
The target URL where webhook payloads will be delivered.
Name
events
Type
array
Description
List of event types this webhook is subscribed to.
Name
is_active
Type
boolean
Description
Whether the webhook is currently active.
Name
created_at
Type
timestamp
Description
When the webhook subscription was created.
Name
updated_at
Type
timestamp
Description
When the webhook subscription was last updated.

POST/webhooks

Create webhook subscription

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

Required attributes

Name
name
Type
string
Description
A human-readable name for the webhook (max 255 characters).
Name
url
Type
string
Description
The target URL for webhook delivery (max 2048 characters). Must be HTTPS.
Name
events
Type
array
Description
List of event types to subscribe to.

Optional attributes

Name
secret
Type
string
Description
A secret key for HMAC-SHA256 signature verification (max 255 characters).
Name
headers
Type
object
Description
Custom headers to include in webhook requests.
Name
X-Org-Id
Type
string
Description
Organization identifier (header). If not provided, uses your default organization.

Request

POST

/v1/webhooks

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
}

GET/webhooks

List webhook subscriptions

This endpoint returns all webhook subscriptions for your organization.

Optional attributes

Name
X-Org-Id
Type
string
Description
Organization identifier (header). If not provided, uses your default organization.

Request

GET

/v1/webhooks

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/webhooks/:subscription_id

Get webhook subscription

This endpoint returns details of a specific webhook subscription.

Required attributes

Name
subscription_id
Type
integer
Description
The unique identifier for the webhook subscription.

Optional attributes

Name
X-Org-Id
Type
string
Description
Organization identifier (header). If not provided, uses your default organization.

Request

GET

/v1/webhooks/1

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
}

PATCH/webhooks/:subscription_id

Update webhook subscription

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

Required attributes

Name
subscription_id
Type
integer
Description
The unique identifier for the webhook subscription.

Optional attributes

Name
name
Type
string
Description
A new name for the webhook.
Name
url
Type
string
Description
A new target URL for webhook delivery.
Name
events
Type
array
Description
Updated list of event types to subscribe to.
Name
secret
Type
string
Description
A new secret key for signature verification.
Name
headers
Type
object
Description
Updated custom headers.
Name
is_active
Type
boolean
Description
Enable or disable the webhook.
Name
X-Org-Id
Type
string
Description
Organization identifier (header). If not provided, uses your default organization.

Request

PATCH

/v1/webhooks/1

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/webhooks/:subscription_id

Delete webhook subscription

This endpoint deletes a webhook subscription. This action cannot be undone.

Required attributes

Name
subscription_id
Type
integer
Description
The unique identifier for the webhook subscription to delete.

Optional attributes

Name
X-Org-Id
Type
string
Description
Organization identifier (header). If not provided, uses your default organization.

Request

DELETE

/v1/webhooks/1

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

GET/webhooks/:subscription_id/logs

List webhook delivery logs

This endpoint returns delivery logs for a specific webhook subscription, showing all delivery attempts including retries.

Required attributes

Name
subscription_id
Type
integer
Description
The unique identifier for the webhook subscription.

Optional attributes

Name
limit
Type
integer
Description
Maximum number of logs to return (default: 50).
Name
offset
Type
integer
Description
Number of logs to skip for pagination (default: 0).
Name
X-Org-Id
Type
string
Description
Organization identifier (header). If not provided, uses your default organization.

Request

GET

/v1/webhooks/1/logs

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
}

GET/webhooks/logs/all

List all delivery logs

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

Optional attributes

Name
event_type
Type
string
Description
Filter logs by event type.
Name
limit
Type
integer
Description
Maximum number of logs to return (default: 50).
Name
offset
Type
integer
Description
Number of logs to skip for pagination (default: 0).
Name
X-Org-Id
Type
string
Description
Organization identifier (header). If not provided, uses your default organization.

Request

GET

/v1/webhooks/logs/all

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
}

POST/webhooks/:subscription_id/test

Test webhook

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

Name
subscription_id
Type
integer
Description
The unique identifier for the webhook subscription to test.

Optional attributes

Name
X-Org-Id
Type
string
Description
Organization identifier (header). If not provided, uses your default organization.

Request

POST

/v1/webhooks/1/test

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