Webhook

Create a webhook endpoint

Register an HTTPS endpoint to receive event deliveries. A signing secret (whsec_…) is generated and returned ONCE in the response — store it now; it is never retrievable again. The receiver verifies the webhook-signature header with it (Standard Webhooks).

post/v1/webhooks/applications/{appId}/endpoints

Request

  • Base URL: https://api.prod.keyban.io
  • URL: https://api.prod.keyban.io/v1/webhooks/applications/{appId}/endpoints
  • Auth: API key in header X-Api-Key

Path parameters

appIdstring required

Request body

urlstring uri required

Absolute HTTPS URL that receives the POST deliveries. HTTP is rejected; private, loopback and link-local hosts and cloud metadata endpoints are blocked server-side (SSRF protection).

eventTypesstring[] required

Event types this endpoint subscribes to. A delivery is sent only when the event type is in this list.

enabledboolean required

When false, no delivery is sent — the endpoint (and its secrets) are kept so it can be re-enabled later.

Example request

{
  "url": "https://api.example.com/hooks/keyban",
  "eventTypes": [
    "dpp.passport.created",
    "dpp.passport.updated"
  ],
  "enabled": true
}

Response

The created endpoint, including its signing secret (shown once)

idstring uuid required

Entity UUID

createdAtstring date-time required

Creation date (ISO 8601)

updatedAtstring date-time required

Last update date (ISO 8601)

applicationIdstring uuid required

Application (tenant) that owns this endpoint.

urlstring uri required

HTTPS URL that receives the deliveries.

eventTypesstring[] required

Event types this endpoint is subscribed to.

enabledboolean required

Whether deliveries are currently sent to this endpoint.

secretstring required

Standard Webhooks signing secret (whsec_<base64>). Returned ONCE at creation or rotation and never again — store it now. The receiver verifies the webhook-signature header with it (e.g. the standardwebhooks library).

Example response

{
  "applicationId": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://api.example.com/hooks/keyban",
  "eventTypes": [
    "dpp.passport.updated"
  ],
  "enabled": true,
  "secret": "whsec_MfKQ9rG3xX0m9V2s1qv4b7Yc8d0e2f4g"
}

Changes

No recorded changes to this operation across all 1 revision of this API.