Webhook event types

Normalized event envelope

Every Developer Platform event has a stable evt_ id, an exact type, an environment, an ISO 8601 creation time, and normalized data. The envelope is used directly by yanola and yanola_with_raw payload modes.

import type {
  YanolaWebhookPayload,
} from "@yanola/whatsapp"

async function processEvent(event: YanolaWebhookPayload) {
  switch (event.type) {
    case "whatsapp.message.received":
      await handleInboundMessage(event)
      break
    case "whatsapp.message.failed":
      await handleMessageFailure(event)
      break
    default:
      await recordObservedEvent(event)
  }
}

Supported event types

Sent is not delivered

whatsapp.message.sent means the outbound message was accepted by Yanola or Meta. It is not proof that the recipient device received or read it.

Use whatsapp.message.delivered and whatsapp.message.read for later provider confirmations. A message can instead emit whatsapp.message.failed when it reaches a terminal failure.

Event data projections

Event read endpoints and normalized webhook payloads never expose provider credentials, internal database IDs, raw-payload storage references, or raw Meta payloads.

Deduplicate and tolerate reordering

1. Use the normalized event.id or yanola-event-id as the business deduplication key.
2. Use yanola-delivery-id only to diagnose one automatic or replay delivery.
3. Persist the event before acknowledging it.
4. Make downstream side effects idempotent because automatic retries and manual replay can deliver the same event again.
5. Do not require events to arrive in lifecycle order; compare message state and timestamps before applying a transition.

Inspect retained events

An API key with events:read can list and retrieve the same normalized public events for reconciliation. Reads are restricted to the key's Yanola Account, Agent Project, environment, and permitted Senders.

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

const event = await yanola.events.retrieve("evt_...")

console.log(event.type)
console.log(event.data.message?.id)
console.log(event.data.conversation?.id)

Subscription strategy

1. Subscribe only to event types the endpoint actually handles.
2. Use Sender filters when different applications own different numbers.
3. Include yanola.webhook.test on Test Mode endpoints you want to verify from the dashboard.
4. Keep a default branch that records or safely ignores newly handled cases.
5. Update subscriptions before deploying logic that depends on a newly selected event type.