Webhook endpoints

Addresses EOS calls when something happens, signed so you can trust them.

List endpoints

GET/api/v1/webhook-endpoints

Your webhook endpoints.

Permissionwebhooks:read (Read webhook endpoints)
Publishable keyNo: secret keys only
Request
curl "https://eos.aveoevents.com/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer $EOS_API_KEY"
200 response
{
  "object": "list",
  "url": "/api/v1/webhook-endpoints",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "object": "webhook_endpoint",
      "id": 7,
      "url": "https://example.com/hooks/eos",
      "description": "Orders into our CRM",
      "events": [
        "order.paid",
        "order.refunded"
      ],
      "active": true,
      "created_at": "2026-11-20T09:00:00.000Z",
      "last_status": 200,
      "last_attempt_at": "2026-11-20T10:15:02.000Z"
    }
  ]
}

Every field of the response: the webhook endpoint object.

Add an endpoint

POST/api/v1/webhook-endpoints

Adds an https address. The signing secret is in the response once: keep it.

Permissionwebhooks:write (Manage webhook endpoints)
Publishable keyNo: secret keys only
Idempotency-KeyAccepted. How retries stay safe

Body (JSON)

urlstringRequired
Your https address. Private network addresses are refused.
descriptionstring
What it is for.
eventsarray of strings
Event types (20 kinds); leave out or [] for all.

Errors it can give

  • 422plan_limitThe company's plan has no room for another endpoint (Starter has none).
  • 422too_many_endpointsA company can have up to 100 API webhook endpoints.
Request
curl -X POST "https://eos.aveoevents.com/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer $EOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://example.com/hooks/eos","description":"Orders into our CRM","events":["order.paid","order.refunded"]}'
201 response
{
  "object": "webhook_endpoint",
  "id": 7,
  "url": "https://example.com/hooks/eos",
  "description": "Orders into our CRM",
  "events": [
    "order.paid",
    "order.refunded"
  ],
  "active": true,
  "created_at": "2026-11-20T09:00:00.000Z",
  "last_status": null,
  "last_attempt_at": null,
  "secret": "whsec_MfKQ9r8GKYqrTwJg..."
}

Every field of the response: the webhook endpoint object.

Get an endpoint

GET/api/v1/webhook-endpoints/{id}

One endpoint.

Permissionwebhooks:read (Read webhook endpoints)
Publishable keyNo: secret keys only

Path parameters

idintegerRequired
The endpoint's id.

Errors it can give

Request
curl "https://eos.aveoevents.com/api/v1/webhook-endpoints/7" \
  -H "Authorization: Bearer $EOS_API_KEY"
200 response
{
  "object": "webhook_endpoint",
  "id": 7,
  "url": "https://example.com/hooks/eos",
  "description": "Orders into our CRM",
  "events": [
    "order.paid",
    "order.refunded"
  ],
  "active": true,
  "created_at": "2026-11-20T09:00:00.000Z",
  "last_status": 200,
  "last_attempt_at": "2026-11-20T10:15:02.000Z"
}

Every field of the response: the webhook endpoint object.

Change an endpoint

PATCH/api/v1/webhook-endpoints/{id}

Changes its address, description, events, or turns it off and on.

Permissionwebhooks:write (Manage webhook endpoints)
Publishable keyNo: secret keys only

Path parameters

idintegerRequired
The endpoint's id.

Body (JSON)

urlstring
New address.
descriptionstring
New description.
eventsarray of strings
New event types.
activeboolean
On or off.

Errors it can give

Request
curl -X PATCH "https://eos.aveoevents.com/api/v1/webhook-endpoints/7" \
  -H "Authorization: Bearer $EOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":false}'
200 response
{
  "object": "webhook_endpoint",
  "id": 7,
  "url": "https://example.com/hooks/eos",
  "description": "Orders into our CRM",
  "events": [
    "order.paid",
    "order.refunded"
  ],
  "active": false,
  "created_at": "2026-11-20T09:00:00.000Z",
  "last_status": 200,
  "last_attempt_at": "2026-11-20T10:15:02.000Z"
}

Every field of the response: the webhook endpoint object.

Remove an endpoint

DELETE/api/v1/webhook-endpoints/{id}

Removes it; nothing more is sent there.

Permissionwebhooks:write (Manage webhook endpoints)
Publishable keyNo: secret keys only

Path parameters

idintegerRequired
The endpoint's id.

Errors it can give

Request
curl -X DELETE "https://eos.aveoevents.com/api/v1/webhook-endpoints/7" \
  -H "Authorization: Bearer $EOS_API_KEY"
200 response
{
  "object": "webhook_endpoint",
  "id": 7,
  "deleted": true
}

Every field of the response: the webhook endpoint object.

Roll the signing secret

POST/api/v1/webhook-endpoints/{id}/roll-secret

Makes a new signing secret at once; the old one stops working.

Permissionwebhooks:write (Manage webhook endpoints)
Publishable keyNo: secret keys only

Path parameters

idintegerRequired
The endpoint's id.

Errors it can give

Request
curl -X POST "https://eos.aveoevents.com/api/v1/webhook-endpoints/7/roll-secret" \
  -H "Authorization: Bearer $EOS_API_KEY"
200 response
{
  "object": "webhook_endpoint",
  "id": 7,
  "url": "https://example.com/hooks/eos",
  "description": "Orders into our CRM",
  "events": [
    "order.paid",
    "order.refunded"
  ],
  "active": true,
  "created_at": "2026-11-20T09:00:00.000Z",
  "last_status": 200,
  "last_attempt_at": "2026-11-20T10:15:02.000Z",
  "secret": "whsec_Q2Vz9ZpL0..."
}

Every field of the response: the webhook endpoint object.

Send a test event

POST/api/v1/webhook-endpoints/{id}/test

Sends a ping event to the endpoint now and returns the delivery.

Permissionwebhooks:write (Manage webhook endpoints)
Publishable keyNo: secret keys only

Path parameters

idintegerRequired
The endpoint's id.

Errors it can give

Request
curl -X POST "https://eos.aveoevents.com/api/v1/webhook-endpoints/7/test" \
  -H "Authorization: Bearer $EOS_API_KEY"
200 response
{
  "object": "webhook_delivery",
  "id": "msg_2c8d4e6f8a0b4c6d8e0f2a4b6c8d0e2f",
  "type": "ping",
  "created_at": "2026-11-20T10:15:01.000Z",
  "attempts": 1,
  "delivered": true,
  "delivered_at": "2026-11-20T10:15:02.000Z",
  "next_attempt_at": null,
  "last_error": null
}

Every field of the response: the webhook delivery object.

List deliveries

GET/api/v1/webhook-endpoints/{id}/deliveries

What was sent to the endpoint, newest first, with retries and errors.

Permissionwebhooks:read (Read webhook endpoints)
Publishable keyNo: secret keys only
ListsPaged with limit and cursor. Pagination

Path parameters

idintegerRequired
The endpoint's id.

Query parameters

limitinteger
How many to return, 1 to 100. Default 25.
cursorstring
The next_cursor from the previous page.

Errors it can give

Request
curl "https://eos.aveoevents.com/api/v1/webhook-endpoints/7/deliveries" \
  -H "Authorization: Bearer $EOS_API_KEY"
200 response
{
  "object": "list",
  "url": "/api/v1/webhook-endpoints/7/deliveries",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "object": "webhook_delivery",
      "id": "msg_2c8d4e6f8a0b4c6d8e0f2a4b6c8d0e2f",
      "type": "order.paid",
      "created_at": "2026-11-20T10:15:01.000Z",
      "attempts": 1,
      "delivered": true,
      "delivered_at": "2026-11-20T10:15:02.000Z",
      "next_attempt_at": null,
      "last_error": null
    }
  ]
}

Every field of the response: the webhook delivery object.

Retry a delivery

POST/api/v1/webhook-endpoints/{id}/deliveries/{delivery_id}/retry

Sends a delivery again now, even one that already succeeded.

Permissionwebhooks:write (Manage webhook endpoints)
Publishable keyNo: secret keys only

Path parameters

idintegerRequired
The endpoint's id.
delivery_idstringRequired
The delivery's id.

Errors it can give

Request
curl -X POST "https://eos.aveoevents.com/api/v1/webhook-endpoints/7/deliveries/msg_2c8d4e6f8a0b4c6d8e0f2a4b6c8d0e2f/retry" \
  -H "Authorization: Bearer $EOS_API_KEY"
200 response
{
  "object": "webhook_delivery",
  "id": "msg_2c8d4e6f8a0b4c6d8e0f2a4b6c8d0e2f",
  "type": "order.paid",
  "created_at": "2026-11-20T10:15:01.000Z",
  "attempts": 1,
  "delivered": true,
  "delivered_at": "2026-11-20T10:15:02.000Z",
  "next_attempt_at": null,
  "last_error": null
}

Every field of the response: the webhook delivery object.