Motion 5Book a demo

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

  1. Make a URL on your server that accepts POST requests, like https://api.yourbank.com/motion5/webhooks. It must be public HTTPS.
  2. In Developers, open Webhooks, add the URL and choose the events it should get (or all of them).
  3. Copy the signing secret (whsec_…). It's shown once; you can roll a new one at any time.
  4. Press Send test event. Your endpoint gets a ping event, 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.

Request
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"
    }
  }
}
id
string
The event's ID. The same event can arrive more than once (a retry after a timeout), so store the IDs you've handled and skip repeats.
type
string
What happened. See event types.
created_at
time
When it happened. Events can arrive out of order, so use this (and the times inside data) to order them.
livemode
boolean
false for test codes and test pings.
data
object
The objects the event is about.

Check 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.

  1. Read the raw request body, before any JSON parsing (parsing and re-encoding changes the bytes).
  2. Compute HMAC-SHA256(secret, t + "." + body) and compare it with v1 in constant time.
  3. Reject it if t is 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

Deliveries are at least once: rarely, an event arrives twice, so skip event IDs you've seen. If your endpoint was down for longer than the retries, catch up with the API (for example list open conversations).

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.

data
{
  "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).

data
{
  "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.

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"
  }
}

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.

data
{
  "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).

data
{
  "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.

data
{
  "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.

data
{
  "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.

data
{
  "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.

data
{
  "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
  }
}