Webhooks

Receive real-time notifications for payment events.

Webhooks allow your application to react to events that happen in the MoniPay protocol, such as a customer completing a payment.

Supported Events

| Event | Description | | :--- | :--- | | payment.completed | Sent when a transaction is confirmed on-chain. | | payment.failed | Sent if a transaction fails or is rejected by the network. | | order.expired | Sent if an order reaches its TTL without being paid. |

Payload Example

json

Verifying Signatures

Every webhook includes an X-MoniPay-Signature header. You must verify this signature to ensure the request is authentic.

Verification Logic (Node.js)

javascript

Best Practices

  1. Return 200 OK: Your server should respond with a 200 status code immediately to acknowledge receipt.
  2. Idempotency: Handle the same event multiple times gracefully in case of retries.
  3. Async Processing: Perform heavy processing (like updating a database) outside the webhook request loop.