Set Up and Handle Diameter Webhooks

Diameter sends real-time event notifications to your endpoint for payments, end users, accounts, and counterparties. Learn how to subscribe and verify.

Diameter uses webhooks to push real-time notifications to your application when important events occur — a payment completes, an end user’s status changes, a new account is created, and more. Rather than polling the API repeatedly, you register an HTTPS endpoint and Diameter delivers a signed POST request to it every time a subscribed event fires. This guide covers subscription setup, signature verification, payload handling, and recovery from missed events.

---

​

Supported event types

Event	Trigger
PAYMENT_WIRE_OUTBOUND_SCREENING_REQUESTED	Payment is under compliance review
PAYMENT_WIRE_OUTBOUND_SCREENING_PASSED	Compliance review approved the payment
PAYMENT_WIRE_OUTBOUND_COMPLETED	Outbound wire settled successfully
PAYMENT_WIRE_OUTBOUND_FAILED	Outbound wire could not be processed
PAYMENT_WIRE_INBOUND_POSTED	An inbound wire was credited to an account
END_USER_CREATED	A new end user record was created
END_USER_UPDATED	An end user’s status or data changed
ACCOUNT_CREATED	A new virtual account was provisioned
COUNTERPARTY_CREATED	A new counterparty was created or became active at a bank

---

​

Retry policy

If your endpoint returns a non-2xx response or times out, Diameter retries the delivery using exponential backoff — up to 8 retries over approximately 6 hours. Each retry uses the same eventId, so your idempotency check will correctly skip duplicate processing.

---

​

Recover missed events

If your endpoint was down for an extended period, use the events search API to find undelivered events and replay them.

---

​

Security best practices

Follow these practices to keep your webhook endpoint secure:

• Always verify the signature — reject any request that fails signature validation with a 401 response
• Check timestamp freshness — reject events older than 5 minutes to prevent replay attacks
• Implement idempotency — deduplicate on eventId before updating your database
• Use HTTPS only — never accept webhook deliveries over plain HTTP
• Keep your secret confidential — store it as an environment variable, never hardcode it or commit it to source control