Register your receiver
Use the sandbox’s endpoint setup for simulated events and a test receiver. Sandbox messages do not reach customers, but events can make real HTTP requests to the URLs you register.
- Open Webhooks in the intended project and add an endpoint.
- Enter the HTTPS URL of your own event receiver. It must accept an HTTP request; a page you open in a browser is not necessarily a receiver.
- Choose the documented events your integration needs. For replies, include message.received; select delivery and failure events for status updates.
- Save the endpoint’s signing secret when it is displayed. Store it separately from the project API key.
Verify and acknowledge each event
Have your developer verify Miss-Blue-Signature against the original request body and the endpoint’s signing secret before processing. Parsing and rebuilding JSON before signature verification can change the bytes and cause a valid signature to fail.
Store an accepted event durably, return a 2xx response promptly, then do longer work asynchronously. Deduplicate by the event envelope’s id so a delivery retry does not create another CRM task or customer message.
If the receiver is not getting events
- Confirm the endpoint is enabled, belongs to the right project, and includes the event type you expect.
- Inspect delivery attempts through the webhook API and compare response codes with your receiver logs.
- Check the URL, certificate, network reachability, and any firewall or login page in front of the receiver.
- If verification fails, check the endpoint’s secret and raw request body; do not disable verification to hide the error.
- After correcting a receiver failure, use Resume if the endpoint is paused. Resuming resets its failure count; reconcile any missing application records separately.
Use automatic typing for an integration
An owner or admin can change Automatic typing indicator on the project’s Webhooks page. When enabled, a new inbound one-to-one iMessage triggers a native typing bubble while your automation prepares its response. Group chats, SMS, and RCS do not trigger it.
The typing bubble does not generate an answer or prove that a workflow is running. Keep a working response path and monitor webhook failures separately.
Pause and deletion have different consequences
Pause stops endpoint deliveries while retaining the endpoint. Removing it discards the endpoint and its signing secret; adding the URL again creates a new secret that your receiver must use.
The API has no message.read webhook. Read state can be checked through message records. Use the event catalog rather than inventing event names from status labels.