Webhook payloads
Webhooks are HTTP POST requests containing JSON. Create a webhook through the Webhooks API and use List webhook triggers to discover the events available on your instance. Installed plugins can affect the available events.
Envelope​
Each key is an event identifier whose value is an array of payloads. Iterate every key and every entry, even when a request contains only one event. Every entry includes an ISO 8601 timestamp. Depending on the transport, this records queue insertion or webhook processing time; it does not replace the entity’s business-event timestamp.
Abbreviated example: the serialized contact normally contains more properties.
{
"mautic.lead_points_change": [
{
"contact": {"id": 123},
"points": {"old_points": 5, "new_points": 10},
"timestamp": "2026-10-01T12:00:00+00:00"
}
]
}
Events​
These keys appear alongside timestamp. Nested entities are serialized in the event’s context; their fields are not guaranteed to match REST responses exactly. Accept additional properties and nullable values.
| Event | Payload keys | Notes |
|---|---|---|
mautic.lead_post_save_new | contact | Newly identified contact. |
mautic.lead_post_save_update | contact | Updated contact. |
mautic.lead_post_delete | id, contact | Use the separate id; the deleted entity can have a null ID. |
mautic.lead_points_change | contact, points | points.old_points and points.new_points are integers. |
mautic.lead_channel_subscription_changed | contact, channel, old_status, new_status | Status strings: contactable, unsubscribed, bounced, manual. |
mautic.lead_company_change | added, contact, company | added is a boolean: association added or removed. |
mautic.company_post_save | company | Company created or updated. |
mautic.company_post_delete | id, company | Use the separate id to identify the deleted company. |
mautic.lead_list_change | contact, segment, action | action is added or removed. |
mautic.email_on_send | email, contact, contentHash, idHash, subject, source, headers | With includeDetails, also content and tokens. This is a send event, not a delivery receipt. |
mautic.email_on_open | stat | Email-open statistic, including related contact/email data. |
mautic.form_on_submit | submission | Form submission and its related data. |
mautic.page_on_hit | hit | Page-hit record and its related data. |
mautic.sms_on_send | smsId, contact, content | May also include transport_message_id when the transport supplies it. |
Headers and signature​
Content-Type is application/json. X-Origin-Base-URL contains the sending instance’s URL; that header alone does not authenticate the sender.
When a secret is configured, Webhook-Signature is the Base64-encoded binary HMAC-SHA256 of the exact HTTP request body:
Base64(HMAC-SHA256(secret, rawRequestBody))
Verify it with a constant-time comparison before processing the payload. Do not decode and re-encode the JSON before calculating the signature: doing so can change the signed bytes. Without a configured secret, no usable signature is supplied.
Delivery and privacy​
Return a 2xx response promptly after accepting the request. The HTTP client does not follow redirects. Make processing idempotent: transport retries can produce duplicates, and arrival order is not a guaranteed business-event order.
Payloads can contain personal data. In particular, includeDetails adds the sent email’s content and tokens. Enable it only when the receiver needs those details.