← Help center

Webhooks: get notified in your own systems

Webhooks let you receive real-time notifications in your own systems when events happen in Yapper. Combined with the public API, they allow you to connect Yapper to your CRM or custom integration platforms (such as Zapier, Make, n8n, or Paragon) to sync data and automate workflows.

Subscribing to webhooks

Webhook subscriptions are managed programmatically via the public API. There is no dashboard configuration interface.

To manage your webhook subscriptions, use the Bearer-token authorized API routes (requires the yapper-api/webhooks or yapper-api/write scope):

• Create: POST /api/v1alpha1/webhooks with your https:// URL and the event types you want. On success, the response includes a signing_secret shown only once — save it to verify signatures.
• List / get / delete: GET /api/v1alpha1/webhooks, GET .../webhooks/{id}, DELETE .../webhooks/{id}.
• Test: POST /api/v1alpha1/webhooks/{id}/ping sends a test ping event to your URL so you can verify connectivity and your signature check.

See the full API reference on the website for exact request and response schemas.

Filtering events

When creating or updating a subscription, you can optionally filter events by a specific customer (customer_id) or communication channel (channel, currently whatsapp).

Supported events

Each webhook payload contains a standard envelope with the event ID, the event type, when it was created, and the customer or channel it relates to. Yapper supports the following event types:

• lifecycle.changed: Triggered when a customer conversation moves to a new phase. The payload includes the playbook ID, the starting phase ID, the new phase ID, and how the transition was triggered.
• customer.updated: Triggered when a customer's contact details or custom fields are updated in the Address book.
• message.received: Triggered when a customer sends a message to your business.
• checklist.completed: Triggered when a checklist or form closes (whether complete, expired, manually closed, escalated, or due to a message delivery failure). Includes the full snapshot of checklist items, statuses, and inputs.
• checklist.updated: Triggered at most once per conversation turn when a customer updates fields in an active checklist. This event is opt-in only (wildcard subscriptions do not receive it) and is skipped if the checklist closes during the same turn.
• report.completed: Triggered when a conversation analysis or report run succeeds or fails. Includes the run's final status and any captured structured fields.
• message.status: Triggered when a message is delivered, read, or fails. This event is opt-in only (wildcard subscriptions do not receive it) to prevent high-volume traffic from overwhelming your servers.
• ping: Sent as a control event when testing your webhook connection.

Webhook payload structure

Each event is sent as a POST request with a JSON payload in the following format:

{
  "id": "evt_01J...",
  "type": "lifecycle.changed",
  "created_at": "2026-06-03T12:00:00Z",
  "account_id": "acc_123...",
  "customer_id": "cust_456...",
  "channel": "whatsapp",
  "data": {
    "playbook_id": "pb_789...",
    "from_phase_id": "phase_abc...",
    "to_phase_id": "phase_xyz...",
    "trigger_source": "customer"
  }
}

Security and signature verification

Every delivery is signed so you can verify it originates from Yapper: the X-Yapper-Signature header is an HMAC-SHA256 of <timestamp>.<raw body> using your subscription's signing_secret, with the timestamp in X-Yapper-Timestamp. Deliveries also carry X-Yapper-Event-Id, X-Yapper-Event-Type, and the attempt number in X-Yapper-Delivery. Always verify the signature and reject mismatches; the signed timestamp prevents replay attacks.

Delivery retry and auto-disabling

• At-least-once delivery: Yapper guarantees that events are delivered at least once. If your server is slow or fails, you may receive the same event multiple times. Always deduplicate incoming events using the X-Yapper-Event-Id header or the id field in the payload.
• Retries: If your server returns a non-2xx status code, times out (10 seconds), or is unreachable, Yapper retries delivery up to 5 times with automatic backoff.
• Automatic disabling (Circuit Breaker): If a subscription fails 15 times consecutively, Yapper automatically disables it to protect performance. You can check the disabled status by retrieving the subscription details via the API.

Inbound transitions: updating conversation phases

You can programmatically change a customer's conversation phase from your CRM or external systems by sending an authorized request to the public API:

POST /api/v1alpha1/customers/{customer_id}/lifecycles/{playbook_id}/transition

• Request headers: Bearer token (requires the yapper-api/transition or yapper-api/write scope).
• Request body:

  {
    "to": "phase_id"
  }
  

Loop prevention

To prevent endless synchronization loops (where an API phase transition triggers an outbound webhook event, which triggers another CRM update, and so on), Yapper automatically suppresses the outbound lifecycle.changed webhook event for any transition initiated via this inbound API route.

Replaying past events (Backfill)

If your systems go offline or miss events, you can query past webhook events using the API:

GET /api/v1alpha1/events?since=<event_id>&limit=N

• How it works: Webhook events are archived for 14 days. Since event IDs are time-sortable and monotonic, you can query for events starting after a specific event ID (since) and paginate through the results oldest-to-newest. The cursor returned is the event ID itself.