Webhooks API

Webhooks let your infrastructure receive real-time HTTP callbacks when Elydora events occur. Register an HTTPS endpoint and subscribe to one or more event types. Elydora signs every delivery with HMAC-SHA256 using the secret you provide at registration time — verify the signature before processing the payload.

List Webhooks

GET

/v1/webhooks

Return all webhook registrations for the current organization.

Auth: 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: security_admin

Request Body

Field	Type	Required	Description
endpoint_url	string	Yes	HTTPS URL that will receive webhook POST requests. Maximum 2048 characters.
events	string[]	Yes	Non-empty array of event type strings to subscribe to. See supported event types below.
secret	string	Yes	Signing secret used to generate HMAC-SHA256 signatures. Minimum 16 characters, maximum 256 characters. Stored encrypted at rest.

Supported Event Types

Field	Type	Required	Description
operation.accepted	string	No	Fired when an operation record (EOR) is successfully submitted and accepted.
epoch.created	string	No	Fired when a new epoch is closed and its Merkle root is committed.
agent.status_changed	string	No	Fired when an agent's status transitions (e.g., active → frozen, frozen → active).

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": "my-super-secret-signing-key-32chars"
  }'

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

Delete Webhook

DELETE

/v1/webhooks/:webhook_id

Permanently remove a webhook registration. Deliveries in-flight will still be attempted.

Auth: security_admin

Path Parameters

Field	Type	Required	Description
webhook_id	string	Yes	UUID 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
}