[Feature request] HMAC-SHA256 signed webhooks

[Mirindi]

Summary

IntaSend webhooks currently support only a shared "challenge" body field
and a bearer header token for authentication. Neither provides cryptographic
proof that the request body has not been tampered with or that the sender
has access to the signing key.

Request

Add HMAC-SHA256 request signing to webhook deliveries, matching the
pattern used by other payment providers:

• Stripe: sends Stripe-Signature header with t=<timestamp>,v1=<signature>
• WhatsApp Cloud API: sends X-Hub-Signature-256: sha256=<hex>
• GitHub: sends X-Hub-Signature-256: sha256=<hex>

Merchants should be able to configure a per-endpoint webhook signing secret
in the dashboard. IntaSend would sign the raw request body with HMAC-SHA256
using that secret and include the signature in an X-Intasend-Signature
header (or similar).

Why

• A leaked bearer token or challenge value allows silent webhook forgery
  with no server-side detection.
• Industry standard for payment webhook security since at least 2017.
• Required for SOC 2 and PCI DSS 4.0 compliance posture of customers
  integrating IntaSend into regulated workflows.

Reference implementation

See Stripe's webhook signature verification algorithm:
https://stripe.com/docs/webhooks/signatures

Filed as a downstream requirement from Mirindi/dukabot#295.

[Ilia01]

This would be a worthwhile improvement.

Signing the raw body is the baseline, but I would go a bit further in the contract so integrators do not have to invent the missing parts themselves.

At minimum I would want the docs/spec to define:

• per-endpoint signing secrets
• signature over the exact raw request body
• a stable delivery or event ID for deduplication
• retry semantics
• sample verification code in a few common server runtimes

If replay protection matters, it is also worth deciding whether the signature format should include a timestamp/version component or whether you want to rely purely on delivery IDs + deduplication on the receiver side.

The main thing I would avoid is a scheme that authenticates the sender but leaves merchants guessing about retries, duplicates, and exact verification inputs.

[Mirindi]

Thanks @Ilia01 — these are exactly the right follow-ups.

We filed this from a production integration (WhatsApp commerce bot with M-Pesa/IntaSend payments) and have hit several of the gaps you're describing:

• Delivery IDs: Without a stable event ID we've had to build our own reconciliation layer to handle duplicate webhook deliveries. A first-class delivery ID from IntaSend would eliminate that.
• Retry semantics: We currently have to assume idempotency windows with no documented guarantee. Knowing the retry count, backoff schedule, and whether the same delivery ID is reused on retry would let us simplify our webhook handler significantly.
• Timestamp in signature: We already verify Stripe-style t=<timestamp>,v1=<sig> signatures for other providers in our stack, so adopting that format would keep verification code consistent across payment backends.

Strongly agree that the spec should cover all of this upfront rather than leaving each integrator to reinvent dedup and replay protection independently.