Register a webhook endpoint

curl -X POST https://tryenvoy.ai/api/v1/webhooks/endpoints \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "url": "https://webhooks.example.com/events",
  "event_types": [
    "shipment.created",
    "shipment.updated"
  ]
}'

{
  "id": "ep_3f9a1c2b-4d7e-4f8a-9b2d-1a2b3c4d5e6f",
  "organization_id": "org_7e8f9a0b-1c2d-3e4f-5a6b-7c8d9e0f1a2b",
  "url": "https://webhooks.example.com/events",
  "description": "Webhook endpoint for shipment event notifications",
  "event_types": [
    "shipment.created",
    "shipment.updated"
  ],
  "headers": {},
  "status": "ACTIVE",
  "disabled_reason": "",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "signing_secret": "whsec_a1b2c3d4e5f6g7h8i9j0"
}

Create a webhook endpoint and receive its signing secret. The secret is returned exactly once in this response — store it immediately; it cannot be retrieved later.

Authentication: Supports API key and bearer token authentication.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

X-Organization-IDstring or nullOptional

Request

This endpoint expects an object.

urlstringRequiredformat: "uri"1-2083 characters

HTTPS URL we will POST events to

event_typeslist of stringsRequired

Allowlist of event type names (e.g. [‘elp_test.scored’]). Must contain at least one entry.

descriptionstring or nullOptional<=500 characters

headersmap from strings to strings or nullOptional

Optional static headers we will include on every request to this endpoint.

Response

Successful Response

idstringformat: "^ep_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"

organization_idstringformat: "^org_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"

urlstring

descriptionstring or null

event_typeslist of strings

headersmap from strings to strings or null

statusenum

Endpoint lifecycle state.

DISABLED is reserved for automatic disable by the auto-disable job; PAUSED is explicitly paused and indicates intent to resume.

disabled_reasonstring or null

created_atdatetime

updated_atdatetime

signing_secretstring

whsec_<base64> — store this; it is not retrievable later.

Errors

401

Unauthorized Error

403

Forbidden Error

422

Unprocessable Entity Error

429

Too Many Requests Error