Webhooks

In some APIs, we will be asking you to send us an endpoint so that we can callback when we have an update. Webhooks allow us to notify your system when specific events occur, enabling real-time updates and seamless integration.

Setting Up Webhooks

You can do this by including the webhook_notification object in your payment link creation request:

{
  "webhook_notification": {
    "endpoint_url": "https://your-domain.com/webhook",
    "authorization_header": "Bearer your-secret-token"
  }
}

Webhook Security

For enhanced security, each webhook request can be authenticated using two HTTP headers.
You can use Authorization, HTTP-WEBHOOK-SIGNATURE, or a combination of both:

• Authorization:
  If you set an authorization_header in your webhook configuration, this value will be sent in the Authorization header of every webhook request.
  Example:

  Authorization: Bearer your-secret-token

  On your server, you should verify this header against a known secret to ensure the request is from a trusted source.

• HTTP-WEBHOOK-SIGNATURE:
  This header contains a cryptographic signature of the webhook payload, allowing you to verify both the integrity and authenticity of the request body.
  Example:

  HTTP-WEBHOOK-SIGNATURE: sha256=abcdef1234567890...

  Your server should recompute the signature using the shared secret and compare it with this header.
  See the HTTP-WEBHOOK-SIGNATURE section for details on generating and verifying signatures.

• Combining Both (Recommended):
  For maximum security, validate both headers:

  • Use Authorization to quickly verify the sender.
  • Use HTTP-WEBHOOK-SIGNATURE to confirm the payload has not been tampered with.

This dual-layer approach ensures requests are both authentic (from a trusted sender) and untampered (payload integrity is preserved).

Reliability and Retry Mechanisms

This call is made by us on a best-effort basis. We implement retry mechanisms to ensure that transient network failures do not affect the ability to call this endpoint. We may call this endpoint more than once with the same payload, so the merchant must ensure that the endpoint is implemented with idempotent behavior.

• Retry Policy: If the target endpoint does not return HTTP 200, we will retry the webhook call up to 3 times, with a 15-minutes delay between each attempt.
• Idempotency: Ensure that your webhook endpoint handles repeated requests safely, without creating duplicate records or side effects.

Implementing these practices will ensure that your integration is reliable, secure, and scalable.