Skip to main content

How it works

When a customer messages one of your company’s WhatsApp numbers, Minimo delivers a whatsapp.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

Permission: WhatsApp.

Request body

Response

The secret is never returned by the API — only hasSecret tells you whether one is set. Store the secret when you create the registration; if you lose it, set a new one with an update.

Manage registrations

Returns all of the company’s webhook registrations (array of the public shape above).
Returns a single registration, or 404 if it doesn’t belong to your company.
All fields optional; only the ones you send are changed. Use status to pause/resume delivery without deleting the registration.
Soft-deletes the registration; delivery stops immediately.
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

Minimo POSTs (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 static headers 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’s secret. 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.
If you register without a secret, deliveries arrive unsigned (no X-Minimo-Signature header). Always set a secret in production.

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.