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.applied and customer.apply_failed.
  • Forget a customer when its data is gone: customer.deleted.
  • Follow up customers that stall: adoption.alert.raised and adoption.alert.resolved.
  • Feed your own helpdesk: support.message.received, support.thread.updated and support.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

JSON
{
  "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.