How it works
When a customer messages one of your company’s WhatsApp numbers, Minimo delivers awhatsapp.message.received event to every active webhook you have registered. The body is a
stable, provider-agnostic Minimo envelope — not the raw Meta/360dialog payload — so your bot
codes against one shape regardless of which transport the number rides.
Delivery is signed (HMAC-SHA256), retried with exponential backoff, and idempotent per
message. You register and manage your endpoints through the API-key-scoped CRUD below.
This is different from the Meta-facing webhook described in Inbound &
Webhooks (which Minimo manages to talk to Meta). Here,
your backend is the receiver and you register its URL.
Register a webhook
WhatsApp.
Request body
Response
Manage registrations
List registrations — GET /public/v1/webhooks/registrations
List registrations — GET /public/v1/webhooks/registrations
Returns all of the company’s webhook registrations (array of the public shape above).
Get one — GET /public/v1/webhooks/registrations/:id
Get one — GET /public/v1/webhooks/registrations/:id
Returns a single registration, or
404 if it doesn’t belong to your company.Update — PUT /public/v1/webhooks/registrations/:id
Update — PUT /public/v1/webhooks/registrations/:id
All fields optional; only the ones you send are changed. Use
status to pause/resume
delivery without deleting the registration.Delete — DELETE /public/v1/webhooks/registrations/:id
Delete — DELETE /public/v1/webhooks/registrations/:id
Soft-deletes the registration; delivery stops immediately.
Delivery logs — GET /public/v1/webhooks/registrations/:id/logs
Delivery logs — GET /public/v1/webhooks/registrations/:id/logs
Returns the most recent delivery attempts (up to 100, newest first) — one row per attempt,
including the final dead-letter row of a failed delivery. Each row carries the delivered
payload, the receiver’s response, the statusCode, an errorMessage when it failed, and
sentAt / createdAt timestamps.The inbound envelope
MinimoPOSTs (or GETs, if you configured method: "GET") this body to your URL. It is
versioned — bump of version signals a breaking change; additive fields do not bump it.
Fields
message.media
Present only when the message carries an attachment:
The envelope is delivered only for inbound messages. Delivery-status events (sent / delivered / read) and
template-approval updates are not forwarded on this surface — see Notes &
Limits.
Delivery headers
Every delivery carries these headers (plus any staticheaders you registered):
Verify the signature
The signature is the HMAC-SHA256 of the exact raw request body (the bytes on the wire), hex-encoded, keyed by your registration’ssecret. Minimo serializes the body once and signs that
same string, so you must verify against the raw body — do not re-serialize a parsed object
first, or key reordering/spacing will break the check.
Retries & idempotency
Retries and provider re-deliveries mean your endpoint can receive the same
wamid more than
once. Always dedup on X-Minimo-Delivery (the wamid) before acting on a message.A registration set to inactive (or deleted) is skipped on the next attempt — delivery stops
cleanly, with no error and no retry.Related
- Send a Message — reply to what you receive
- Read API — backfill history
- Notes & Limits