Webhooks
A subscription ties a URL to one event name in one workspace. Each time that event happens, MessageDesk sends an HTTPPOST to the URL. This is how instant triggers work: an integration provider subscribes when you turn an automation on and unsubscribes when you turn it off.
These are the Developer API’s event subscriptions. The Send Webhook relay action is a separate feature with its own endpoint URL, signing secret and payload, configured in Developer Tools.
Managing subscriptions
One subscription covers one event name. Subscribe once per event you want. Keep the returned
id; it’s the only handle for unsubscribing.
Delivery
Deliveries aren’t signed. Subscription URLs are created only through an authenticated call and providers use unguessable hook URLs, so treat the URL itself as the secret. If you point a subscription at your own endpoint, accept only the payload shapes below and check
workspaceId before acting on anything.
Reliability and limits
Here’s how delivery actually behaves, so you can decide what to trust it with.- Events are pushed as they happen. There’s no polling interval.
- We don’t retry. If a delivery fails, that event is gone. There’s no backoff and no queue holding it for later.
- Events deliver once. There’s no event ID or idempotency key in the payload; if you need a dedupe key, build one from the payload’s fields.
- Order isn’t guaranteed. Two events fired moments apart can arrive out of order. Don’t depend on Contact Created landing before Contact Updated.
- Actions fire triggers. An action taken through the API looks the same as one taken by a person, so Send a message fires
MessageSent, and Create or update a contact firesContactCreatedorContactUpdated. There are no loop guards on our side.
Events and payloads
Only the events below are delivered. Subscribing to any other event name is accepted but never fires. Payloads carry the event itself and not much else; if you need the contact behind a message, look it up with a Find contacts call.See a real payload before any event fires. Each event has a matching Sample endpoint under Triggers, for example Sample inbound messages. It returns up to three of the workspace’s most recent records formatted exactly as the webhook will deliver them. If the workspace has none yet, it returns three generated placeholder records in the same shape. Providers call these to show sample data while you build an automation; they’re not a history API.
MessageReceived, MessageSent
MessageReceived, MessageSent
Schema: For
DeveloperProviderMessageWebhookMessageReceived, from is the contact and to is your workspace number. For MessageSent the two are reversed.ContactCreated, ContactUpdated, ContactDeleted
ContactCreated, ContactUpdated, ContactDeleted
Schema: Contacts are the exception to the thin-payload rule:
DeveloperProviderContactWebhookproperties always carries the workspace’s custom fields, keyed by field name.CommentCreated
CommentCreated
Schema:
DeveloperProviderCommentWebhookCallReceived
CallReceived
Schema: Fires only on numbers where MessageDesk handles both voice and texting. Hosted numbers, where your original carrier still takes calls, don’t fire it.
DeveloperProviderCallWebhookOptOutCreated, OptOutDeleted
OptOutCreated, OptOutDeleted
Schema:
DeveloperProviderOptOutWebhookSee also
- Subscribe to an event and Unsubscribe from an event.
- Relays → Send Webhook. The signed, relay-driven webhook for your own systems.