Webhooks

List Webhooks

GET

/v1/webhooks

Return the webhooks registered for the current organization.

Auth: org_owner, security_admin

Example Request

bash

curl https://api.elydora.com/v1/webhooks \
  -H "Authorization: Bearer <token>"

Response

json

{
  "webhooks": [
    {
      "webhook_id": "0195a1b2-c3d4-7e5f-a6b7-c8d9e0f1a2b3",
      "org_id": "0195a0b1-c2d3-7e4f-a5b6-c7d8e9f0a1b2",
      "endpoint_url": "https://hooks.acme.com/elydora",
      "events": ["operation.accepted", "epoch.created"],
      "status": "active",
      "created_at": 1740700800000,
      "updated_at": 1740700800000
    }
  ]
}

Register Webhook

POST

/v1/webhooks

Auth: org_owner, security_admin

Request Body

Field	Type	Required	Description
endpoint_url	string	Yes	URL that receives the deliveries. Maximum 2048 characters; the endpoint must pass the egress policy.
events	string[]	Yes	Non-empty array of event types from the list below.
secret	string	Yes	HMAC-SHA256 signing secret, 16 to 256 characters. Stored encrypted.

Event Types

Field	Type	Required	Description
operation.accepted	string	No	An operation record was accepted.
epoch.created	string	No	An epoch closed and its Merkle root was committed.
agent.status_changed	string	No	An agent status changed, for example active to frozen.

Example Request

bash

curl -X POST https://api.elydora.com/v1/webhooks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://hooks.acme.com/elydora",
    "events": ["operation.accepted", "epoch.created"],
    "secret": "<signing secret of at least 16 characters>"
  }'

Response

json

{
  "webhook": {
    "webhook_id": "0195a1b2-c3d4-7e5f-a6b7-c8d9e0f1a2b3",
    "org_id": "0195a0b1-c2d3-7e4f-a5b6-c7d8e9f0a1b2",
    "endpoint_url": "https://hooks.acme.com/elydora",
    "events": ["operation.accepted", "epoch.created"],
    "status": "active",
    "created_at": 1740700800000,
    "updated_at": 1740700800000
  }
}

Deliveries

Each delivery is a JSON POST. The X-Elydora-Signature header carries sha256=<hex> where hex is HMAC-SHA256(secret, "<X-Elydora-Webhook-Timestamp>.<raw body>").

json

{
  "event": "operation.accepted",
  "delivery_id": "0195a7b8-c9d0-7e1f-a2b3-c4d5e6f7a8b9",
  "org_id": "0195a0b1-c2d3-7e4f-a5b6-c7d8e9f0a1b2",
  "timestamp": 1772287201000,
  "data": { "operation_id": "0195f2c6-8f4e-7a1b-9c3d-2e4f6a8b0c1d", "agent_id": "agent_underwriter" }
}

Delivery Headers

Field	Type	Required	Description
X-Elydora-Webhook-Event	string	Yes	Event type
X-Elydora-Webhook-Delivery-Id	string	Yes	Unique delivery identifier
X-Elydora-Webhook-Id	string	Yes	Webhook identifier
X-Elydora-Webhook-Timestamp	string	Yes	Unix timestamp in seconds used in the signature
X-Elydora-Signature	string	Yes	sha256=<hex HMAC-SHA256>

Delete Webhook

DELETE

/v1/webhooks/:webhook_id

Remove a webhook registration.

Auth: org_owner, security_admin

Path Parameters

Field	Type	Required	Description
webhook_id	string	Yes	Identifier of the webhook to delete

Example Request

bash

curl -X DELETE https://api.elydora.com/v1/webhooks/0195a1b2-c3d4-7e5f-a6b7-c8d9e0f1a2b3 \
  -H "Authorization: Bearer <token>"

Response

json

{
  "success": true
}