Inbound webhooks

Register endpoints that trigger tasks or emit events, with HMAC signing.

An inbound webhook is an endpoint Meteor exposes so a third party can POST to it. When an event arrives, Meteor can trigger a task or emit an internal event. It needs the webhooks:manage scope.

These are inbound webhooks (third party → Meteor). If what you want is for Meteor to notify you when something happens (run.completed, etc.), jump to Outbound events below.

Create a webhook

const wh = await met.webhooks.create({
  name: 'Lead intake',
  binding_type: 'generic',        // 'task' runs a task; 'generic' only emits an event
  verifier_type: 'hmac_sha256',   // 'none' for unsigned
});

console.log(wh.url);      // the URL the third party points at
console.log(wh.secret);   // ⚠️ shown ONCE only

Store the secret the moment you receive it: it is never shown again. With it you verify that each delivery really came from your integration.

Verify the signature

The third party signs the body with the secret (HMAC-SHA256) and sends the signature in a header. On Meteor's side, verification is automatic if the webhook is hmac_sha256.

Rotate the secret

If you suspect it leaked:

const rotated = await met.webhooks.rotateSecret(wh.id);
console.log(rotated.secret);   // new secret; invalidates the previous one

See deliveries

const events = await met.webhooks.events(wh.id, { limit: 20 });
const sample = await met.webhooks.sample(wh.id);   // last payload received

sample is handy for setting up the payload's field mapping.

Connect a flow

A generic webhook can trigger a flow when it receives an event (connectFlow in the API). That way an external POST starts a full automation inside Meteor.

Outbound events (Meteor → your server)

An outbound event is Meteor POSTing to *you* when something happens in your workspace — for example, when a Run finishes. You register an endpoint, choose which events you want, and Meteor delivers each one signed with HMAC so you can verify it came from Meteor.

Register an endpoint

You register the endpoint from your panel: Developers → Activity → Webhooks. You choose your server's URL and which events you want (or * for all of them). On creation, Meteor shows you the signing secret (whsec_...) once only — store it, you need it to verify every delivery.

Change an endpoint's events

To add or remove events, or change the URL or description, use PATCH /webhook-endpoints/{id}. The signing secret doesn't change: your verification keeps working as is, with nothing to redeploy. enabled_events replaces the whole list, so to add an event send the current list plus the new one:

const [ep] = await met.webhooks.subscriptions.list();
await met.webhooks.subscriptions.update(ep.id, {
  enabled_events: [...ep.enabled_events, 'contact.message.failed'],
});

If you subscribed with *, there's nothing to do: new catalog events reach you on their own.

Event catalog

There are 30. The scope column is the permission a key must carry to receive that event: the same one you would read that resource with through the API.

* is not an event: it is the "everything in the catalog" wildcard, and it covers the ones we add later too. If you would rather hear about a new event before you start receiving it, subscribe to the explicit list.

Five things that save you a debugging session:

• channel.run.* is not run.*. A run.* is an API Run, with an id you can query; a channel.run.* is the Met answering a channel message (WhatsApp and the rest) and leaves no row in Runs. If you only listen for run.completed, channel replies never reach you.
• app.authorized and app.revoked are delivered to the workspace that owns the OAuth app — yours, the developer's — not to the one that authorizes it.
• Test deliveries arrive with type: "ping", which is not in the catalog. Your handler should ignore what it does not recognise instead of failing.
• A full conversation is two events. contact.message.received carries what the contact writes; the replies —from the Met, from your team in the inbox, or from the owner on WhatsApp Business on their phone— arrive in contact.message.sent. Subscribe only to the first and you never see the replies. contact.message.sent carries sent_by (met or operator) and sent_from: met, phone (the owner's phone), flow (a flow or automation) or meteor (any other send from Met: inbox, broadcast, template or API). For finer detail, use origin: panel (a person in the app), api (your integration with an API key or SDK), mcp, flow, automation, broadcast, met, phone or system. It's the same field every message carries in GET /contacts/{id}/messages. Internal conversation notes —assignment, status or tag changes— are not sent as messages: they never reach the contact. Both carry attachments in the same shape (url, type, name) and, on voice notes, transcript with the text: the contact's and also the ones your team records.
• A message that didn't arrive gets its own event. contact.message.failed fires when a message to a contact goes undelivered: the provider rejected it on send, or WhatsApp marked it failed later, usually within minutes. It carries the same fields as contact.message.sent, plus error —with code, WhatsApp's code when there is one, and message— and template_name when it was a template. The code separates causes that call for different actions: 131026, the number can't receive the message (check it); 131049, Meta capped marketing templates to that person (the number is fine: space out your sends); 132012, a parameter doesn't match the template (fix the send). It fires once per message. The same data stays in metadata.delivery_status and metadata.delivery_error on each message in GET /contacts/{id}/messages.

The API returns this same table, always current:

const { data } = await met.webhooks.subscriptions.eventTypes();
// [{ type: 'run.completed', description: '…', scope: 'runs:read' }, …]

Verify the signature

Every delivery carries the header X-Met-Signature: t=<ts>,v1=<hmac>. Never process an event without verifying it — use the SDK helper, which does the verification timing-safe and checks the timestamp (anti-replay):

import Met from '@meteor.ia/sdk';
const met = new Met(process.env.MET_API_KEY!);

app.post('/webhooks/met', (req, res) => {
  let event;
  try {
    event = met.webhooks.constructEvent(req.rawBody, req.headers['x-met-signature'], WHSEC);
  } catch {
    return res.status(400).send('invalid signature');
  }
  if (event.type === 'run.completed') { /* ... */ }
  res.sendStatus(200);   // answer 2xx quickly; Meteor retries otherwise.
});

You need the raw body to verify the signature — configure your framework not to re-serialize the JSON before constructEvent.

Retries

If your endpoint doesn't answer 2xx within 15 seconds, Meteor retries with growing waits: the first attempt, then after 1 min → 5 min → 30 min → 2 h → 6 h, 6 attempts in total (about 8.6 hours from the first). After that it marks the delivery as failed; you can send it again with POST /webhook-endpoints/{id}/deliveries/{deliveryId}/retry or POST /events/{id}/replay. Every retry carries the same event id, also in the X-Met-Event-Id header: use it so you never process the same thing twice. Deliveries go out in parallel, so ordering is not guaranteed: sort by created. The attempt log per endpoint is in your Workbench (Developers section).