Skip to main content

Webhook Integration & Security

Webhooks allow your application to receive real-time asynchronous notifications whenever a payment is approved, debited, or settled.

Webhook Signature Verification (HMAC-SHA512)

Every webhook request sent by Handle includes the X-Handle-Signature header:
  • t: UNIX timestamp (in seconds) of when the webhook was generated.
  • v1: HMAC-SHA512(t + "." + rawBody, webhookSigningSecret).

Node.js / TypeScript Verification Code


Event Types

charge.success

Triggered immediately when the customer approves the payment and bank debit is confirmed:

Exponential Backoff Retry Policy

Handle will never flood or spam your server during outages. If your server returns anything other than 200 OK, Handle retries using an exponential schedule:
  • Attempt 1: Immediate (T=0T=0)
  • Attempt 2: T+5 minsT+5\text{ mins}
  • Attempt 3: T+30 minsT+30\text{ mins}
  • Attempt 4: T+2 hoursT+2\text{ hours}
  • Attempt 5: T+8 hoursT+8\text{ hours}
  • Attempt 6 (Final): T+24 hoursT+24\text{ hours}

Manual Replay in Dashboard

You can manually re-send any past webhook event with 1-click in the Handle Merchant Dashboard → Webhook Logs.