Console
Documentation/Webhooks and event feed

Webhooks and event feed

Build a durable inbound agent without duplicate replies.

Receive events

Register a public HTTPS endpoint with an appropriate scoped credential. Verify the signature over the exact raw request body before parsing it. Keep your endpoint secret in server storage and rotate it when compromised.

Signatures use X-Sqkii-Timestamp (Unix seconds), X-Sqkii-Signature (v1= followed by an HMAC-SHA256 hex digest), and X-Sqkii-Event-Id. The signed bytes are timestamp + "." + exact raw body. Reject timestamps more than 300 seconds from your clock and compare digests in constant time.

ts
import { verifyWebhook } from '@sqkii/whatsapp';
const valid = verifyWebhook(rawBody, timestampHeader, signatureHeader, webhookSecret);

Your receiver should durably persist a verified event and return success quickly. Run model calls and business workflows asynchronously. Sqkii can retry failed deliveries, so deduplicate by event ID.

Event provenance

An event identifies its project, number and conversation where relevant. Inspect provenance before running an agent:

SourceDefault treatment
New live inbound messageEligible for routing and inbound usage
Imported historyStore for context; do not trigger a new reply
Business-app outbound echoSynchronize; do not count as an API send
Delivery/status updateUpdate message state; do not create an inbound charge
Passive/standby messageObserve; do not send without ownership

Delivery semantics

Assume at-least-once delivery and possible reordering. There is no global ordering guarantee across numbers. Track each conversation independently, and do not let an older status overwrite a later terminal status.

Failed deliveries appear in event logs with attempts and error details. Replay preserves the original event identity, so a replay should not produce another business action in an idempotent consumer.

Local development

Use the resumable event feed and CLI watch command when your agent runs locally. The watcher must be running to receive new work. Store its cursor durably; processing an event twice should be harmless.

Sending a reply

Check your conversation assignment, automation state, Meta ownership and messaging-window eligibility. Templates may be required outside the service window. Do not use imported history to infer that a new service window is open.

Subscription grants

A subscription created with a project- or number-restricted API key inherits those restrictions. An empty project or number list cannot expand that key's access. Revoking or expiring the creating key stops its webhook and route targets from receiving subsequent deliveries. Event replay rechecks the target's current grant and preserves the original event ID.

Prepared 18 November 2026 · Sqkii Pte. Ltd.