Propelus
Webhooks

Create Webhook

Register a webhook. The server synchronously POSTs an activation payload { "event": "activation", "code": "<6-char>" } to the configured url using the configured authentication headers and records the outcome on the webhook:

  • 2xx response → record stored with status: pending, response code: created_not_verified. The caller's endpoint received the 6-character verification code; submit it to POST /v2/webhooks/{webhookId}/activate to transition the webhook to active.

  • non-2xx / network failure → record stored with status: failed, response code: created_failed. The id is returned in the same response envelope so the caller can PATCH /v2/webhooks/{webhookId} to retry the activation handshake (PATCH always re-runs the handshake when the stored record is failed).

At most one webhook per (client, eventType) may be in active, pending, or failed state at once. pending and failed records carry a 7-day TTL; abandoned records are reaped automatically.

POST
/v2/webhooks

Authorization

apiKey clientId
x-api-key<token>

In: header

x-client-id<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v2/webhooks" \  -H "Content-Type: application/json" \  -d '{    "eventType": "credentialVerified",    "url": "https://my.site/externalEvents",    "signature": {      "key": "a3f8c92e5d1b4f7a9e6c2d8b3f5a1c4e"    }  }'
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": 201,
  "code": "created_not_verified",
  "detail": "string"
}
{
  "status": 400,
  "code": "missing_fields",
  "detail": "string",
  "errors": [
    {
      "detail": "string",
      "pointer": "string",
      "parameter": "string",
      "header": "string",
      "code": "string"
    }
  ]
}
{
  "status": 400,
  "code": "missing_fields",
  "detail": "string",
  "errors": [
    {
      "detail": "string",
      "pointer": "string",
      "parameter": "string",
      "header": "string",
      "code": "string"
    }
  ]
}
{
  "status": 400,
  "code": "missing_fields",
  "detail": "string",
  "errors": [
    {
      "detail": "string",
      "pointer": "string",
      "parameter": "string",
      "header": "string",
      "code": "string"
    }
  ]
}
{
  "status": 400,
  "code": "missing_fields",
  "detail": "string",
  "errors": [
    {
      "detail": "string",
      "pointer": "string",
      "parameter": "string",
      "header": "string",
      "code": "string"
    }
  ]
}
{
  "status": 429,
  "detail": "string",
  "code": "f5d62b05-370e-48be-a755-8675ca146431"
}
{
  "status": 400,
  "code": "missing_fields",
  "detail": "string",
  "errors": [
    {
      "detail": "string",
      "pointer": "string",
      "parameter": "string",
      "header": "string",
      "code": "string"
    }
  ]
}
{
  "status": 500,
  "detail": "string",
  "code": "unexpected_error"
}

Activate Webhook POST

Confirm ownership of a `pending` webhook by submitting the 6-character `verificationCode` that the server included in the activation POST during `POST /v2/webhooks` (or `PATCH /v2/webhooks/{webhookId}` when reactivation was triggered). The code was delivered to the webhook's configured `url`; retrieve it from your endpoint's request log or capture buffer. On success the webhook transitions to `active` and the stored `activationCode` and last-handshake `response` are cleared. Returns `404` if the webhook does not exist, was soft-deleted, or belongs to another client; `400` if the webhook is already `active`, or if the submitted code does not match. To prevent code-enumeration probes revealing whether a webhook is already activated, the already-active check is performed before the code comparison.

Delete Webhook DELETE

Soft-delete a webhook. The record is retained for 48h with `status=deleted` before being pruned by DynamoDB TTL.