Signed events
Verify the raw request body before trusting an event.
Receive WhatsApp replies through a reliable webhook
Send inbound messages, delivery changes and connection events back to your application through a signed, replay-safe webhook.
For developers designing the boundary between WhatsApp and an application backend.Replay safe
Deduplicate by workspace and event identifier.
Fast acknowledgement
Queue durable work and respond before downstream processing.
What arrives at your endpoint
ChatRail posts inbound messages, delivery-state changes and connection events to the HTTPS endpoint configured for the workspace. Each event carries an identifier, timestamp, type and relevant resource data. Treat the payload as untrusted until its signature and timestamp are verified.
Define one stable ingress boundary
Use a dedicated HTTPS route for ChatRail rather than mixing it with browser actions or unrelated provider callbacks. Enforce a small request limit, a supported content type and a narrow method allow-list.
Verify the exact bytes
const digest = createHmac("sha256", process.env.WEBHOOK_SECRET)
.update(rawBody)
.digest("hex");
if (!safeEqual(receivedSignature, digest)) {
return response.status(401).end();
}Verify against the raw body—not a parsed and re-serialized object. Compare fixed-length values in constant time and reject stale timestamps to reduce replay exposure.
Acknowledge before expensive work
Authenticate the event, persist or durably enqueue it, then return success. Database joins, model calls and third-party requests should run outside the request path. This keeps latency predictable and reduces unnecessary webhook retries.
Delivery is at least once
Assume the same event may arrive more than once. Insert the event ID behind a unique workspace-scoped constraint before producing side effects. Return success for an already processed event instead of repeating a customer action.
Keep event types separate
Inbound replies, message-state transitions and connection health serve different purposes. Route them to explicit handlers, tolerate unknown future event types and apply monotonic rules so a late delivered event cannot overwrite a later read state.
Observe without collecting excess data
Record latency, event type, attempt count and a redacted error category. Avoid logging message content, authorization headers, QR material or full phone numbers.
Frequently asked questions
What response should my endpoint return?
Return a successful 2xx response after verification and durable acceptance.
Can I point ChatRail at an automation platform?
Yes, when it can preserve the raw body or otherwise perform the required signature verification safely.
Can I respond to the webhook with a WhatsApp message?
Acknowledge the webhook quickly, then send through the messaging API from a worker. Do not make delivery depend on a long synchronous response.
Why can the same event arrive twice?
Retries protect against network and server failures. Idempotent processing turns that delivery model into predictable application behavior.
Should I log the full payload?
Prefer event IDs, types and redacted diagnostics. Message bodies and phone numbers may contain sensitive data.
CONTROL THE OUTCOME
Start with one event and one reply path.
Prove the operational loop before increasing traffic or automation.
Start free