Products
Webhooks
Motion 5 tells your servers what happens as it happens: codes delivered or failed, customers asking for a person, their messages, delivery reports, transfers, disputes and card freezes. Each event is a signed HTTPS POST.
Set up an endpoint
- Make a URL on your server that accepts POST requests, like
https://api.yourbank.com/motion5/webhooks. It must be public HTTPS. - In Developers, open Webhooks, add the URL and choose the events it should get (or all of them).
- Copy the signing secret (
whsec_…). It's shown once; you can roll a new one at any time. - Press Send test event. Your endpoint gets a
pingevent, and Recent deliveries shows how it answered.
You can have up to 10 endpoints, turn each on or off, and resend any delivery from the same page.
What we send
A POST with a JSON body: the event. data holds the objects the event is about, in the same shape the API returns them.
POST /motion5/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: Motion5-Webhooks/1
Motion5-Event-Id: evt_01JD3W2B9N8M7K6J5H4G3F2D1S
Motion5-Event-Type: message.received
Motion5-Delivery-Id: whd_01JD3W2BA1B2C3D4E5F6G7H8J9
Motion5-Signature: t=1763285500,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
{
"id": "evt_01JD3W2B9N8M7K6J5H4G3F2D1S",
"object": "event",
"type": "message.received",
"created_at": "2026-11-16T09:31:40.204Z",
"livemode": true,
"data": {
"message": {
"object": "message",
"id": "msg_01JD3W2A3B4C5D6E7F8G9H0J1K",
"conversation_id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"direction": "in",
"sender": "customer",
"agent": null,
"type": "text",
"text": "I was debited twice for one transfer",
"reply": null,
"media": null,
"status": "received",
"error": null,
"created_at": "2026-11-16T09:31:40.118Z"
}
}
}idtypecreated_atlivemodefalse for test codes and test pings.dataCheck the signature
Anyone can POST to a public URL, so check every request came from Motion 5. The Motion5-Signature header has a timestamp t and a signature v1: the hex HMAC-SHA256 of {t}.{raw body}, keyed with your endpoint's secret.
- Read the raw request body, before any JSON parsing (parsing and re-encoding changes the bytes).
- Compute
HMAC-SHA256(secret, t + "." + body)and compare it withv1in constant time. - Reject it if
tis more than 5 minutes from your clock, so an old request can't be replayed.
import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.MOTION5_WEBHOOK_SECRET; // whsec_…
function isFromMotion5(header = "", rawBody) {
const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
const t = Number(parts.t);
if (!t || !parts.v1 || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = createHmac("sha256", SECRET).update(`${t}.${rawBody}`).digest();
const given = Buffer.from(parts.v1, "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
}
app.post("/motion5/webhooks", express.raw({ type: "application/json" }), (req, res) => {
const raw = req.body.toString("utf8");
if (!isFromMotion5(req.get("Motion5-Signature"), raw)) return res.sendStatus(400);
const event = JSON.parse(raw);
res.sendStatus(200); // answer first…
queue.add(event); // …then do the work
});Responding and retries
- Answer with any 2xx status within 10 seconds. Do slow work after answering (a queue), or a slow reply counts as a failure.
- Redirects aren't followed: a 3xx counts as a failure. Use the final URL.
- Anything else is retried after 10 seconds, 1 minute, 5 minutes, 30 minutes, then 1, 2, 4 and 8 hours: 9 tries over about 16 hours. After that the delivery is marked failed, and you can resend it from Developers.
- An endpoint that's turned off gets nothing, and deliveries waiting for it are marked failed.
Build for repeats and gaps
Event types
Choose the types each endpoint gets, or all of them. New types may be added; an endpoint set to all events will get them too, so ignore types you don't handle. The ping test event has data.message only.
handoff.requested
A customer asked to talk to a person. Includes their last 10 messages, so your agent has the context.
{
"conversation": {
"object": "conversation",
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"customer": {
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567",
"account_linked": true
},
"handoff": {
"object": "handoff",
"id": "hnd_01JD3W1R2S3T4U5V6W7X8Y9Z0A",
"status": "waiting",
"assigned_to": null,
"requested_at": "2026-11-16T09:31:12.402Z",
"assigned_at": null,
"resolved_at": null,
"resolved_by": null
},
"window": {
"open": true,
"closes_at": "2026-11-17T09:31:10.000Z"
}
},
"recent_messages": [
{
"object": "message",
"id": "msg_01JD3W2A3B4C5D6E7F8G9H0J1K",
"conversation_id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"direction": "in",
"sender": "customer",
"agent": null,
"type": "reply",
"text": "Talk to a person",
"reply": {
"id": "agent",
"title": "Talk to a person"
},
"media": null,
"status": "received",
"error": null,
"created_at": "2026-11-16T09:31:40.118Z"
}
]
}handoff.assigned
An agent took the conversation, in your helpdesk or in the Motion 5 inbox. handoff.assigned_to says who and where (via: api or inbox).
{
"conversation": {
"object": "conversation",
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"customer": {
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567",
"account_linked": true
},
"handoff": {
"object": "handoff",
"id": "hnd_01JD3W1R2S3T4U5V6W7X8Y9Z0A",
"status": "active",
"assigned_to": {
"id": "agent-42",
"name": "Ngozi Eke",
"via": "api"
},
"requested_at": "2026-11-16T09:31:12.402Z",
"assigned_at": "2026-11-16T09:32:05.000Z",
"resolved_at": null,
"resolved_by": null
},
"window": {
"open": true,
"closes_at": "2026-11-17T09:31:10.000Z"
}
}
}message.received
The customer wrote while a person has the conversation (waiting or active). Photos, voice notes, videos and documents carry a media.url to download them.
{
"message": {
"object": "message",
"id": "msg_01JD3W2A3B4C5D6E7F8G9H0J1K",
"conversation_id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"direction": "in",
"sender": "customer",
"agent": null,
"type": "text",
"text": "I was debited twice for one transfer",
"reply": null,
"media": null,
"status": "received",
"error": null,
"created_at": "2026-11-16T09:31:40.118Z"
}
}message.status
A message from one of your agents was delivered, read or failed (with error). Each status is sent once, and never goes backwards.
{
"message": {
"object": "message",
"id": "msg_01JD3W3C4D5E6F7G8H9J0K1M2N",
"conversation_id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"direction": "out",
"sender": "agent",
"agent": {
"id": "agent-42",
"name": "Ngozi Eke",
"via": "api"
},
"type": "text",
"text": "Hi Ada, I'm looking into it now.",
"reply": null,
"media": null,
"status": "delivered",
"error": null,
"created_at": "2026-11-16T09:31:40.118Z"
}
}handoff.resolved
The conversation went back to the bot. resolved_by is agent (handed back), customer (they sent MENU) or timeout (24 hours without a word from the customer).
{
"conversation": {
"object": "conversation",
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"customer": {
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567",
"account_linked": true
},
"handoff": {
"object": "handoff",
"id": "hnd_01JD3W1R2S3T4U5V6W7X8Y9Z0A",
"status": "resolved",
"assigned_to": null,
"requested_at": "2026-11-16T09:31:12.402Z",
"assigned_at": null,
"resolved_at": "2026-11-16T09:50:00.000Z",
"resolved_by": "agent"
},
"window": {
"open": true,
"closes_at": "2026-11-17T09:31:10.000Z"
}
}
}transfer.succeeded
A customer sent money from WhatsApp and it went through. Also transfer.failed; see transfer events.
{
"transfer": {
"object": "transfer",
"id": "trf_01JD4C2K8N5P7Q9R1S3T5V7W9X",
"status": "successful",
"amount": 500000,
"fee": 1000,
"currency": "NGN",
"narration": "WhatsApp transfer",
"recipient": {
"bank_code": "058",
"bank_name": "GTBank",
"account_number": "0123456789",
"account_name": "TUNDE ADEYEMI"
},
"account": {
"reference": "ACC-0012345678",
"number": "••••5678"
},
"customer": {
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567"
},
"bank_reference": "NIP0000132611161042001234",
"failure_reason": null,
"created_at": "2026-11-16T10:42:03.118Z",
"completed_at": "2026-11-16T10:42:04.902Z"
}
}dispute.created
A customer reported a payment in WhatsApp. Also dispute.updated when it moves on; see dispute events.
{
"dispute": {
"object": "dispute",
"id": "dsp_01JD4A7C2M9Q3R5T8V1W4X6Y0Z",
"reference": "DSP-7KQ3M9XA",
"status": "open",
"reason": "failed_debited",
"note": null,
"customer": {
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567"
},
"account": {
"reference": "ACC-0012345678",
"number": "••••5678"
},
"transaction": {
"reference": "FT26314AB12C",
"date": "2026-11-14T10:42:00.000Z",
"amount": -250000,
"currency": "NGN",
"narration": "Transfer to Tunde A."
},
"resolution": null,
"created_at": "2026-11-16T09:12:44.207Z",
"updated_at": "2026-11-16T09:12:44.207Z",
"resolved_at": null
}
}card.frozen
A customer froze a card in WhatsApp. Also card.unfrozen, after their PIN.
{
"card": {
"id": "card_8f31c2d0",
"brand": "Verve",
"last4": "4821",
"expires": "08/28",
"status": "frozen"
},
"account": {
"reference": "ACC-0012345678",
"number": "••••5678"
},
"customer": {
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567"
}
}otp.delivered
A code reached the phone. Also otp.read, otp.verified, and otp.failed with a reason; see OTP events.
{
"otp": {
"object": "otp",
"id": "otp_01JD3W8K2Q9F7T6Y5X4V3B2N1M",
"phone": "+234803••••567",
"purpose": "login",
"status": "pending",
"delivery": "delivered",
"attempts": 0,
"max_attempts": 5,
"channel": "whatsapp",
"mode": "live",
"created_at": "2026-11-16T09:30:00.000Z",
"expires_at": "2026-11-16T09:40:00.000Z",
"delivered_at": "2026-11-16T09:30:02.114Z",
"read_at": null,
"verified_at": null
}
}