Webhooks
An introduction to receiving provider callbacks with MailRaft.
Webhooks
The API implements GET and POST /webhooks/integrations/:id. A concrete URL is issued only after the operator binds the integration to your company. Unbound requests are denied, never silently acknowledged.
Webhook features
With MailRaft’s webhook foundations, you can:
- Verify webhook requests to check that requests originate from the configured provider before their bodies are parsed.
- Route callbacks to an explicitly bound integration. Unbound requests are denied.
- Reject stale or replayed events using timestamp bounds and durable replay detection.
- Keep an audit of the outcome without recording provider payloads, verification tokens or customer content.
Quickstart
Start with an approved WhatsApp integration and an operator-issued webhook URL.
To configure the callback for your integration, you need to:
Bind the integration to your company
The operator must bind the integration before a concrete webhook URL is issued. Use the canonical endpoint without a trailing slash.
Verify the callback
Use the configured verification token for the provider challenge. Keep verification queries and tokens out of logs and support messages.
Check the acceptance gates
A successful challenge does not establish production messaging or delivery. Meta business verification and production messaging remain deferred.
Verify requests
WhatsApp verifies the GET challenge and signs POST bodies with the app secret. Bodies are limited to 256 KiB; account/phone routing, timestamp bounds, durable replay detection and sanitized audits are enforced. Keep the verify token out of logs and support messages.
GET verification requires hub.mode=subscribe, a constant-time matching hub.verify_token and a bounded hub.challenge. The exact challenge is returned with HTTP 200 and text/plain. Use the issued canonical path without a trailing slash. Do not put verification queries in access logs.
POST verifies the HMAC over the original bounded body before parsing. Invalid signatures, wrong account/phone bindings, malformed schemas, unsupported events, stale timestamps and replays remain denied. Audit fields contain bounded rejection_code and signature_verdict values, never raw payloads. Meta production messaging remains deferred.
Project code examples
Browse MailRaft source references and HTTP examples in Node.js, Python, Ruby, PHP, Go, Rust, Java, .NET, Elixir and cURL.