Overview & Signature Verification

HitchPay sends real-time POST notifications to your configured webhook URL for cross-border transactions and KYC events.

Events

Webhook Endpoint Requirements

• Must be a publicly accessible HTTPS endpoint
• Must accept POST requests with a JSON body
• Must respond with HTTP 200 OK within 10 seconds

Signature Verification

Every webhook is signed using HMAC SHA256 with your webhook_secret. Always verify the x-hitchpay-signature header before processing any event.

const crypto = require('crypto');

function verifyWebhook(req, webhookSecret) {
  const signature = req.headers['x-hitchpay-signature'];
  const computed = 'sha256=' + crypto
    .createHmac('sha256', webhookSecret)
    .update(req.rawBody)
    .digest('hex');
  return computed === signature;
}

⚠️ Always use req.rawBody (the raw, unparsed request body) when computing the HMAC. Parsing the JSON first will cause signature mismatches.

Retry Schedule

If your endpoint does not respond with 200 OK, HitchPay retries delivery up to 5 times:

Deduplication

Webhooks may be delivered more than once for the same event. Always use the reference field to uniquely identify transactions and handle deduplication on your end.

Webhook Payload Structure

All cross-border webhook payloads follow this shape:

{
  "event": "payment.success",
  "data": { },
  "sent_at": "2026-03-16T01:00:00.000Z"
}

See the individual event pages for full payload examples:

• KYC Status Update
• Transfer Status Update
• Collection Status Update
• Payment Success Event
• Payment Failed Event

Verifying webhook authenticity

Every webhook request includes an x-hitchpay-signature header — an HMAC-SHA256 signature. Verify it the same way you do for other event types before trusting the payload.

Important: Always verify the signature before acting on a webhook payload, and treat webhooks as the source of truth for pending transactions rather than assuming success.