Webhooks API

Webhooks deliver durable notifications to an HTTPS endpoint owned by the organization. Delivery is at least once: consumers must verify signatures, tolerate duplicates and reordering, and fetch current resource state when correctness matters.

Ownership and Roles

An API Client may create and manage only its own webhook endpoints. Events are filtered through the same license, Role, field, and resource rules as API reads. Changing the client's Roles immediately changes what future deliveries may contain.

Create an endpoint

POST /v1/webhook-endpoints

Operation ID: createWebhookEndpoint. Required header: Idempotency-Key.

{
  "url": "https://integrations.example.com/eos/webhooks",
  "events": ["task.updated", "invoice.sent", "run.completed"],
  "description": "Production Eos listener"
}

The response returns a signing secret exactly once. Store it in a secret manager. Eos accepts only HTTPS endpoints, blocks private or unsafe network destinations, and may require a verification challenge before activation.

List, get, and update endpoints

• GET /v1/webhook-endpoints — listWebhookEndpoints
• GET /v1/webhook-endpoints/{endpoint_id} — getWebhookEndpoint
• PATCH /v1/webhook-endpoints/{endpoint_id} — updateWebhookEndpoint, If-Match
• POST /v1/webhook-endpoints/{endpoint_id}/rotate-secret — rotateWebhookEndpointSecret, Idempotency-Key
• POST /v1/webhook-endpoints/{endpoint_id}/disable — disableWebhookEndpoint, Idempotency-Key
• POST /v1/webhook-endpoints/{endpoint_id}/enable — enableWebhookEndpoint, Idempotency-Key

Secret rotation returns the new secret once and supports a short documented overlap window so consumers can deploy safely.

Event envelope

{
  "id": "evt_01J8RK6KS3SXQ1R5C2NW9N1N6J",
  "type": "invoice.sent",
  "api_version": "v1",
  "created_at": "2026-08-22T12:00:00Z",
  "organization_id": "org_01J8PZZRJBBG2AX1SQA6ZVY6QY",
  "data": {
    "object": {"type": "invoice", "id": "inv_01J8R6MB55Q2BEY9NE7NQE3J4S", "version": 4}
  }
}

Events carry stable identifiers and a minimal authorized resource projection. Consumers should retrieve the resource for its current full representation.

Verify signatures

Each request includes:

• Eos-Webhook-Id: the event ID
• Eos-Webhook-Timestamp: Unix seconds
• Eos-Webhook-Signature: one or more versioned HMAC-SHA256 signatures

Eos-Webhook-Signature contains comma-separated v1=<lowercase hexadecimal digest> values. Compute HMAC-SHA256 over timestamp + "." + raw_request_body with the endpoint secret, compare at least one v1 digest in constant time, and reject timestamps more than five minutes from the receiving system's clock. Verify the raw bytes before JSON parsing. Deduplicate on event ID.

Published SDK fixtures will include valid, invalid, rotated-secret, stale-timestamp, and modified-payload test vectors.

Delivery, retries, and responses

Return any 2xx response within ten seconds. Redirects are not followed. Timeouts, network failures, 429, and 5xx responses are retried with exponential backoff for 72 hours. Most other 4xx responses are treated as permanent. Events and delivery diagnostics remain available for 30 days. Repeated failures may automatically disable an endpoint and emit an administrator notification.

Inspect and replay deliveries

• GET /v1/webhook-endpoints/{endpoint_id}/deliveries — listWebhookDeliveries
• GET /v1/webhook-endpoints/{endpoint_id}/deliveries/{delivery_id} — getWebhookDelivery
• POST /v1/webhook-endpoints/{endpoint_id}/deliveries/{delivery_id}/replay — replayWebhookDelivery, Idempotency-Key
• POST /v1/webhook-endpoints/{endpoint_id}/test — testWebhookEndpoint, Idempotency-Key

Replay is available only inside the event retention window and creates a new delivery attempt for the same event ID.

Initial event families

• project.*, task.*, time_entry.*, and ticket.*
• invoice.*, payment.*, and file.*
• approval.created and approval.updated
• report_run.*, run.*, and conversation.message.created
• integration_connection.updated

The endpoint-creation API returns the exact supported event names. Unknown names are rejected.

Common errors

WEBHOOK_ENDPOINT_NOT_FOUND, WEBHOOK_EVENT_NOT_SUPPORTED, WEBHOOK_URL_UNSAFE, WEBHOOK_VERIFICATION_FAILED, WEBHOOK_SECRET_NOT_AVAILABLE, WEBHOOK_DELIVERY_NOT_FOUND, and WEBHOOK_REPLAY_EXPIRED.

Back to Eos API v1 overview.