Webhook signature
A webhook signature is a cryptographic proof that a webhook payload came from the expected source. The sender hashes the payload with a shared secret; the receiver re-hashes and compares. If they match, the payload is authentic. If they do not, the receiver discards the request.
Why it matters
Webhooks are the dominant pattern for "let me know when something happens" between services. Stripe sends a webhook when a payment succeeds. Twilio sends one when a call connects. Slack sends one when a message arrives. The receiving service has a public URL; anyone can POST to it.
Without signatures, the receiving URL is open to spoofing. An attacker could send fake webhooks pretending to be Stripe; the receiver would process the fake event as real. For payment-related webhooks, this is a serious vulnerability.
The signature pattern fixes it:
- The sender and receiver share a secret (provisioned during integration setup).
- The sender hashes the payload + timestamp with the shared secret using HMAC-SHA256.
- The signature goes in a header (
X-Stripe-Signature,X-Hub-Signature-256, etc.). - The receiver re-hashes and compares. If the hashes match, the payload is authentic.
The pattern works because the attacker does not have the shared secret. They cannot produce a valid signature for a fake payload. The receiver's verification step is fast (microseconds) and bulletproof.
The trade-off: every webhook integration has its own signature scheme (Stripe vs Twilio vs Slack format different things differently). Adapter code matters.
How Ajeris handles this
Every webhook Ajeris receives goes through signature verification before being processed. Stripe webhooks verify against the STRIPE_WEBHOOK_SECRET; Twilio webhooks verify against the Twilio signature; custom MCP callbacks verify against the user-provided HMAC secret. Failed verification rejects the request with 401 and writes the rejection to the audit trail.
Outbound webhooks Ajeris sends to user infrastructure are signed the same way. Users get an HMAC secret with their custom MCP setup; their endpoints can verify the request came from Ajeris.
