• 228 destinations
  • No KYC, ever
  • Bitcoin, Monero, USDT and 4 more

API and integration

HMAC signature (webhooks)

An HMAC signature is a keyed hash (HMAC-SHA256) of a webhook's timestamp and body, computed with a secret shared with your endpoint, so you can verify that the event came from the gateway and was not altered.

Anyone who learns your webhook URL can send it a request, so a signature is what separates the gateway's events from forgeries. HMAC, defined in RFC 2104, combines a secret key with a hash function, here SHA-256, to produce a code that only holders of the secret can compute. The gateway signs each event with the endpoint's secret; your handler recomputes the code over the same bytes and accepts the event only if the two match. The signature proves origin and integrity. It does not hide the content; that is the job of HTTPS.

Two details make the scheme robust. The signed string includes a timestamp, a separator and the raw body, so a captured request cannot be replayed later: the timestamp is checked against a tolerance, and changing it breaks the signature. And the comparison runs in constant time, so that response timing reveals nothing about how many characters matched.

Example

Suppose an attacker captures a genuine message.failed event and, an hour later, resends it with the status changed to delivered. The altered body no longer matches the signature. Resent unaltered, it carries an hour-old timestamp and fails the tolerance check. Either way the handler rejects it.

Common mistakes

  • Verifying a re-serialised body: parsing and re-encoding JSON changes whitespace and key order, so the code never matches. Parse after verifying.
  • Using the API key instead of the endpoint's signing secret.
  • Comparing with ordinary string equality.
  • Rejecting events during a secret rotation; check both secrets until the overlap ends.

At SMSMeteor: X-Meteor-Signature reads t=…,v1=…, where v1 is the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the endpoint secret; X-Meteor-Timestamp carries the timestamp in Unix seconds. Five minutes is a sensible tolerance. Secrets are rotated from the panel, with old and new both valid for 24 hours. Replayed events get a new timestamp and signature, and test-key webhooks are signed like live ones. Details are in the webhooks documentation and on the security page.

Go further

See the term in practice.An email address opens the account, the rate card is public, payment is crypto, the test key is free.
Start sending