> ## Documentation Index
> Fetch the complete documentation index at: https://diameterpay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**.

> [!WARNING]
>
> 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](https://diameterpay.mintlify.site/api-reference/webhooks/update-subscription.md) 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

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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"
}
```

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.