Create a Webhook Subscription to Receive API Events

POST /v1/webhook-subscriptions — Register an HTTPS endpoint to receive Diameter event notifications. Returns a one-time signing secret on creation.

Registering a webhook subscription tells Diameter where to deliver event notifications for your tenant. You provide a target HTTPS URL and an optional list of event types to filter; if you omit eventTypes (or pass an empty array), the subscription receives every event. On successful creation the API returns a one-time secret — a 64-character hex string you must immediately store in a secure vault, as it cannot be retrieved again.

The secret field is only present in the 201 Created response. If you lose it, you must rotate the secret by calling the Update Subscription endpoint.

​

Endpoint

POST /v1/webhook-subscriptions

Required scope: webhooks.write

​

Request Headers

Header	Required	Description
Authorization	Yes	Bearer {access_token}
x-idempotency-key	Yes	A UUID v4 that makes this request safe to retry
Content-Type	Yes	application/json

​

Request Body

name · string · required

A human-readable label for this subscription, e.g. "Payment Notifications". Used for display purposes only.

url · string · required

The HTTPS endpoint that will receive event payloads. Must use https://, must not rely on redirects, and must be reachable from the public internet. The domain must be on your tenant’s validDomains list.

eventTypes · array

An array of event type strings to subscribe to. Omit or pass an empty array [] to subscribe to all events. Accepted values:

Category	Event Types
Wire Outbound	PAYMENT_WIRE_OUTBOUND_SCREENING_REQUESTED, PAYMENT_WIRE_OUTBOUND_SCREENING_PASSED, PAYMENT_WIRE_OUTBOUND_ROUTED, PAYMENT_WIRE_OUTBOUND_RECEIVED_BY_PARTNER, PAYMENT_WIRE_OUTBOUND_COMPLETED, PAYMENT_WIRE_OUTBOUND_FAILED, PAYMENT_WIRE_OUTBOUND_POSTED, PAYMENT_WIRE_OUTBOUND_RETURN_POSTED
Wire Inbound	PAYMENT_WIRE_INBOUND_POSTED, PAYMENT_WIRE_INBOUND_RETURN_POSTED
Internal Payments	PAYMENT_INTERNAL_SCREENING_REQUESTED, PAYMENT_INTERNAL_SCREENING_PASSED, PAYMENT_INTERNAL_ROUTED, PAYMENT_INTERNAL_RECEIVED_BY_PARTNER, PAYMENT_INTERNAL_COMPLETED, PAYMENT_INTERNAL_FAILED
ACH	PAYMENT_ACH_RECEIVER_CREDIT_POSTED, PAYMENT_ACH_RECEIVER_DEBIT_POSTED
End Users	END_USER_CREATED, END_USER_UPDATED
Counterparties	COUNTERPARTY_CREATED, COUNTERPARTY_UPDATED
Accounts	ACCOUNT_CREATED, ACCOUNT_UPDATED

​

Response — 201 Created

id · string

UUID of the newly created webhook subscription.

name · string

The friendly name provided in the request.

url · string

The HTTPS endpoint URL.

eventTypes · array

The event types this subscription is configured to receive. An empty array indicates a subscription to all events.

isActive · boolean

true when the subscription is actively delivering events.

secret · string

A 64-character hex string used to verify the X-Diameter-Signature header on incoming webhook requests. Present only on creation — store it immediately.

createdAt · string

ISO 8601 timestamp of when the subscription was created.

updatedAt · string

ISO 8601 timestamp of the most recent update.

​

Examples

​

Create a subscription for payment events

curl --request POST \
  --url https://api.diameterpay.com/v1/webhook-subscriptions \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: e4d6f8a2-3b1c-4f9e-a7d0-12c3e5b8f091' \
  --data '{
    "name": "Payment Notifications",
    "url": "https://hooks.yourapp.com/diameter/payments",
    "eventTypes": [
      "PAYMENT_WIRE_OUTBOUND_COMPLETED",
      "PAYMENT_WIRE_OUTBOUND_FAILED",
      "PAYMENT_WIRE_INBOUND_POSTED",
      "PAYMENT_ACH_RECEIVER_CREDIT_POSTED"
    ]
  }'

​

Subscribe to all events

curl --request POST \
  --url https://api.diameterpay.com/v1/webhook-subscriptions \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-key: a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  --data '{
    "name": "All Events Firehose",
    "url": "https://hooks.yourapp.com/diameter/all"
  }'

​

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Payment Notifications",
  "url": "https://hooks.yourapp.com/diameter/payments",
  "eventTypes": [
    "PAYMENT_WIRE_OUTBOUND_COMPLETED",
    "PAYMENT_WIRE_OUTBOUND_FAILED",
    "PAYMENT_WIRE_INBOUND_POSTED",
    "PAYMENT_ACH_RECEIVER_CREDIT_POSTED"
  ],
  "isActive": true,
  "secret": "a3f8c2e1d4b7a6f09e8d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2",
  "createdAt": "2024-06-01T12:00:00.000Z",
  "updatedAt": "2024-06-01T12:00:00.000Z"
}

Save the secret value to your secrets manager immediately. Use it to compute and verify the X-Diameter-Signature HMAC-SHA256 header on every inbound webhook request.