Webhooks
Event types
Every event a webhook endpoint can receive, when it is sent and what its data holds.
Every event has the same outer shape: id, type, api_version, created_at, sandbox, actor and data. What is sent explains them. This page lists every type and what its data holds. The same events, with the same bodies, are in List events for 90 days. A token only reads back the events it may read: support.* events need the support:read ability and webhook_endpoint.* events webhooks:manage, on top of customers:read. An event the token may not read is not in the list, and answers 404 by its ID.
Customers
data.customer is the whole customer as Get a customer returns it, as it was right after the event. data.details holds what the table says, and is an empty object ({}) when the table says nothing.
| Event | Sent when | data.details |
|---|---|---|
customer.created |
A customer is created, as a draft or to be set up at once, in the portal or over the API | seller: the name of the seller it is credited to, or null |
customer.provisioning |
The setup starts: a customer is submitted, or a failed setup is retried | retry: true on a retry |
customer.step |
A setup step finished. The customer in the event is already on the next step | step, label |
customer.live |
The company is set up and the admin is invited | url, admin_email |
customer.failed |
The setup stopped on an error. Monotree is alerted | step, reason |
customer.updated |
Settings changed, in the portal or over the API | fields: the parts that changed, such as company_name, company_id, country, employees, languages, admin, brand, external_ref |
customer.applied |
Changed settings reached the customer's app | fields |
customer.apply_failed |
Monotree could not apply something to the customer's app: changed settings, or a suspend, resume, delete or resent invitation. What you sent stays stored, and Monotree looks at it | command (update, suspend, resume, delete or resend_invite), reason |
customer.invite_resent |
The admin's invitation was sent again, in the portal or with Resend the admin invitation | email |
customer.suspended |
Access was paused | reason, when one was given |
customer.resumed |
Access was given back | |
customer.cancelled |
The customer was cancelled and will be deleted after 30 days | delete_after |
customer.deleted |
The company and its data were deleted: a draft at once, any other customer 30 days after it was cancelled |
A change to a default_language shows as languages in fields, and a change to a logo or colour as brand.
Sellers
data.seller is the seller, without the three fields that say how the person signs in: two_factor, passkeys and last_login_at are never in an event. Read them with Get a seller and a token that has security:read. There is no data.details.
| Event | Sent when |
|---|---|
seller.created |
A seller is added: in the portal, with Add a seller, or by a seller_ref seen for the first time on a new customer |
seller.updated |
A seller's name, email, role or external_ref was changed: in the portal's Sellers page, over the API, by the person on their own account page, or by a seller_name that names a seller known only by a reference |
seller.disabled |
A seller was disabled and can no longer sign in |
seller.enabled |
A disabled seller was enabled again |
seller.invited |
An invitation to the portal was emailed to a seller. Never in the sandbox, where no email is sent |
Adoption alerts
data.adoption_alert is the whole adoption alert, with its customer's id, company_name and external_ref. There is no data.details, and actor is null.
| Event | Sent when |
|---|---|
adoption.alert.raised |
A live customer stalls: few signed in, activity dropped, or its numbers stopped coming. An alert was opened, or re-opened after the customer had recovered |
adoption.alert.resolved |
The alert was closed: the customer recovered, or is no longer live |
Support
data.thread is the support thread without its messages. actor says who did it. Besides user, token and system it can be assistant (the assistant sent its own draft, or left a thread to a person) and, on support.message.received, customer (the person at the customer who wrote). On support.message.sent it is whoever wrote the answer; on support.message.delivered and support.message.failed it is system, as Monotree reports the delivery.
| Event | Sent when | Also in data |
|---|---|---|
support.thread.created |
A support thread started: someone at a customer wrote, or you wrote to them first | |
support.thread.updated |
A support thread changed | change: what changed, such as closed, reopened, assigned, snoozed, merged or deleted (the support guide has the list, and more values may be added). details, where there is more to say |
support.thread.rated |
The customer said whether your answer helped. The thread carries the rating |
|
support.message.received |
Someone at a customer wrote in a thread | message |
support.message.sent |
An answer left your support desk: yours, the assistant's or the automatic reply | message |
support.message.delivered |
Monotree delivered an answer to the customer. Never in the sandbox, where nothing is delivered | message |
support.message.failed |
An answer could not be delivered. The message's delivery.error says why. Never in the sandbox |
message |
Two events are about an escalation and carry data.escalation instead of a thread:
| Event | Sent when |
|---|---|
support.escalation.created |
A support thread was escalated to Monotree |
support.escalation.updated |
An escalation changed: Monotree picked it up (received), fixed, released or declined it, or another thread was added to it. Every change of status sends one |
Webhook endpoints
| Event | Sent when | data |
|---|---|---|
webhook_endpoint.paused |
Monotree paused one of your endpoints because it only failed for days. Sent to your other endpoints | webhook_endpoint (the endpoint, without its secret) and details: reason (failing), failed_deliveries, days |
The test event
ping is not an event you subscribe to. It is sent to one endpoint when you press Test in the portal or call Send a test event. Its id starts with evt_test_, its data holds only a message, and it is not kept in List events.
Choosing events
Most integrations need only a few:
- Show the state in your product:
customer.live,customer.failed,customer.suspended,customer.resumed,customer.cancelled. - A live progress bar while a seller waits: add
customer.step. - Keep your copy of the settings in step:
customer.updated,customer.appliedandcustomer.apply_failed. - Forget a customer when its data is gone:
customer.deleted. - Follow up customers that stall:
adoption.alert.raisedandadoption.alert.resolved. - Feed your own helpdesk:
support.message.received,support.thread.updatedandsupport.message.failed. - Know when an endpoint stopped hearing:
webhook_endpoint.paused, on a second endpoint.
Subscribe to * to get every event, including ones added in later versions. An endpoint that names an unknown type is refused with 422. New event types never change the shape of existing ones.
Example: customer.failed
{
"id": "evt_01jd0b3s8k2m5q7t9w1y4a6c8e",
"object": "event",
"type": "customer.failed",
"api_version": "1.0.0",
"created_at": "2026-11-11T14:31:40Z",
"sandbox": false,
"actor": { "type": "system", "name": "Monotree" },
"data": {
"customer": {
"id": "cus_01jd0b2q5r8t1v4x7z0b3d6f9h",
"object": "customer",
"status": "failed",
"company_id": "librairievoltaire",
"provisioning": { "step": "install", "step_label": "Setting up the company", "steps_done": 1, "steps_total": 6, "failure_reason": "The company could not be set up. Monotree has been alerted and will look at it." }
},
"details": { "step": "install", "reason": "The company could not be set up. Monotree has been alerted and will look at it." }
}
}The customer is trimmed here; a real event carries all its fields.