API reference
Webhooks
Endpoints on your side that Monotree calls when something changes, and the deliveries made to them.
Base URL https://partners.monotree.com/api/v1
· every call needs a token
Endpoints
get/webhooks
List webhook endpoints
post
/webhooks
Add a webhook endpoint
get
/webhooks/{webhook}
Get a webhook endpoint
patch
/webhooks/{webhook}
Change a webhook endpoint
delete
/webhooks/{webhook}
Delete a webhook endpoint
post
/webhooks/{webhook}/test
Send a test event
post
/webhooks/{webhook}/rotate-secret
Rotate the signing secret
get
/webhooks/{webhook}/deliveries
List deliveries
post
/webhooks/{webhook}/deliveries/redeliver-failed
Redeliver failed deliveries
get
/webhooks/{webhook}/deliveries/{delivery}
Get a delivery
post
/webhooks/{webhook}/deliveries/{delivery}/redeliver
Redeliver a delivery
List webhook endpoints
/webhooks
webhooks:manage Your webhook endpoints of the token's mode (live or sandbox), newest first. Only the endpoints the token may touch are listed: those whose events it may all read, both the types an endpoint is subscribed to and the types among the deliveries it still holds. See Which endpoints a token sees.
Parameters
limit
integer · query
default 25 · up to 100
cursor
string · query
next_cursor of the page before, for the next page. Send the same filters with it.
Response · 200 A page of endpoints.
object
string
has_more
boolean
next_cursor
string, nullable
cursor for the next page.
data
array of objects
Errors
invalid_cursor: the cursor is not one this API gave out.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
validation_error: a field is missing or invalid; fields says which.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/webhooks \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/webhooks', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/webhooks', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/webhooks",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"object": "list",
"has_more": false,
"next_cursor": "string",
"data": [
{
"id": "whe_01jd1f4c8m2p0r6t9w3y5a7c1e",
"object": "webhook_endpoint",
"url": "https://api.acme.example/hooks/monotree",
"description": "Back office, production",
"events": [
"customer.live",
"customer.failed"
],
"active": true,
"paused_at": "2026-11-12T09:41:00Z",
"paused_reason": "manual",
"secret": "string",
"previous_secret_expires_at": "2026-11-12T09:41:00Z",
"failed_24h": 0,
"last_delivery": {
"id": "whd_01jd1g2h3j4k5m6n7p8q9r0s1t",
"status": "delivered",
"response_code": 200,
"created_at": "2026-11-12T09:42:18Z"
},
"sandbox": false,
"created_at": "2026-11-10T14:05:00Z"
}
]
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Add a webhook endpoint
/webhooks
webhooks:manage Adds an endpoint for the token's mode: one added with a sandbox token gets sandbox events only. The signing secret is in the answer to this call only; store it. The URL must be https and lead to a public address: one whose host resolves to a private, loopback, link-local or reserved address is refused, here and again on every delivery. At most 10 endpoints per mode. An endpoint is only sent events its maker may read: the token needs the ability that reads each type in events (customers:read for customer.*, seller.* and adoption.* events, support:read for support.*, webhooks:manage for webhook_endpoint.*), and all of them for *, which is also what leaving events out means. Otherwise the answer is 403 and names the ability that is missing.
Accepts an optional Idempotency-Key header to make a retry safe.
Request body
url
required
string
https URL that leads to a public address. http and local hosts are refused.
at most 255 characters
description
string, nullable
at most 120 characters
events
array of strings
* for every event, also ones added later, or the types you want from the Event types guide (customer.live, customer.failed, …). An unknown type is refused.
default ["*"]
active
boolean
false adds the endpoint paused.
default true
Response · 201 The endpoint, with its secret.
id
string
object
string
url
string
description
string, nullable
events
array of strings
* for all.
active
boolean
paused_at
string, nullable
paused_reason
string, nullable
manual: paused by you. failing: paused by Monotree after 5 days of nothing but failed deliveries, at least 20 of them.
one of manual, failing
secret
string
whsec_…). Only in the answers to Add a webhook endpoint and Rotate the signing secret.
previous_secret_expires_at
string, nullable
failed_24h
integer
failed in the last 24 hours.
last_delivery
object, nullable
id
string
status
string
one of pending, delivered, retrying, failed
response_code
integer, nullable
created_at
string
sandbox
boolean
created_at
string
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks webhooks:manage, or the ability that reads one of the events asked for (all of them for * or when events is left out). The message names it.
limit_reached: you already have 10 endpoints in this mode. endpoints_busy: another request is adding an endpoint right now; try again in a moment. idempotency_in_progress: a call with the same Idempotency-Key is still running. idempotency_key_taken: the key was used by another of your tokens.
validation_error: a field is missing or invalid; fields says which. idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X POST https://partners.monotree.com/api/v1/webhooks \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.acme.example/hooks/monotree",
"description": "Back office, production",
"events": [
"customer.live",
"customer.failed"
]
}'$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/webhooks', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'url' => 'https://api.acme.example/hooks/monotree',
'description' => 'Back office, production',
'events' => [
'customer.live',
'customer.failed',
],
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/webhooks', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"url": "https://api.acme.example/hooks/monotree",
"description": "Back office, production",
"events": [
"customer.live",
"customer.failed"
]
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/webhooks",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"url": "https://api.acme.example/hooks/monotree",
"description": "Back office, production",
"events": [
"customer.live",
"customer.failed"
]
},
)
data = response.json(){
"id": "whe_01jd1f4c8m2p0r6t9w3y5a7c1e",
"object": "webhook_endpoint",
"url": "https://api.acme.example/hooks/monotree",
"description": "Back office, production",
"events": [
"customer.live",
"customer.failed"
],
"active": true,
"paused_at": "2026-11-12T09:41:00Z",
"paused_reason": "manual",
"secret": "string",
"previous_secret_expires_at": "2026-11-12T09:41:00Z",
"failed_24h": 0,
"last_delivery": {
"id": "whd_01jd1g2h3j4k5m6n7p8q9r0s1t",
"status": "delivered",
"response_code": 200,
"created_at": "2026-11-12T09:42:18Z"
},
"sandbox": false,
"created_at": "2026-11-10T14:05:00Z"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Get a webhook endpoint
/webhooks/{webhook}
webhooks:manage One endpoint with its health: failed_24h and last_delivery. The signing secret is not in this answer. A token only finds an endpoint whose events it may all read (the types it is subscribed to and the types among its deliveries); any other endpoint answers 404: see Which endpoints a token sees.
Parameters
webhook
required
string · path
whe_…).
Response · 200 The endpoint.
id
string
object
string
url
string
description
string, nullable
events
array of strings
* for all.
active
boolean
paused_at
string, nullable
paused_reason
string, nullable
manual: paused by you. failing: paused by Monotree after 5 days of nothing but failed deliveries, at least 20 of them.
one of manual, failing
secret
string
whsec_…). Only in the answers to Add a webhook endpoint and Rotate the signing secret.
previous_secret_expires_at
string, nullable
failed_24h
integer
failed in the last 24 hours.
last_delivery
object, nullable
id
string
status
string
one of pending, delivered, retrying, failed
response_code
integer, nullable
created_at
string
sandbox
boolean
created_at
string
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such webhook endpoint.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "whe_01jd1f4c8m2p0r6t9w3y5a7c1e",
"object": "webhook_endpoint",
"url": "https://api.acme.example/hooks/monotree",
"description": "Back office, production",
"events": [
"customer.live",
"customer.failed"
],
"active": true,
"paused_at": "2026-11-12T09:41:00Z",
"paused_reason": "manual",
"secret": "string",
"previous_secret_expires_at": "2026-11-12T09:41:00Z",
"failed_24h": 0,
"last_delivery": {
"id": "whd_01jd1g2h3j4k5m6n7p8q9r0s1t",
"status": "delivered",
"response_code": 200,
"created_at": "2026-11-12T09:42:18Z"
},
"sandbox": false,
"created_at": "2026-11-10T14:05:00Z"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Change a webhook endpoint
/webhooks/{webhook}
webhooks:manage Change the URL or the events, or pause it with active: false. active: true switches a paused endpoint on again, also one Monotree paused because it only failed. New events need the abilities that read them, as when adding one: a token cannot widen an endpoint to events it may not read (403). A token only finds an endpoint whose events it may all read (the types it is subscribed to and the types among its deliveries); any other endpoint answers 404: see Which endpoints a token sees. So a token cannot point, pause or describe an endpoint for events it may not read either.
Parameters
webhook
required
string · path
whe_…).
Request body
url
string
https URL that leads to a public address. http and local hosts are refused.
at most 255 characters
description
string, nullable
at most 120 characters
events
array of strings
active
boolean
false pauses the endpoint, true switches it on again.
Response · 200 The endpoint.
id
string
object
string
url
string
description
string, nullable
events
array of strings
* for all.
active
boolean
paused_at
string, nullable
paused_reason
string, nullable
manual: paused by you. failing: paused by Monotree after 5 days of nothing but failed deliveries, at least 20 of them.
one of manual, failing
secret
string
whsec_…). Only in the answers to Add a webhook endpoint and Rotate the signing secret.
previous_secret_expires_at
string, nullable
failed_24h
integer
failed in the last 24 hours.
last_delivery
object, nullable
id
string
status
string
one of pending, delivered, retrying, failed
response_code
integer, nullable
created_at
string
sandbox
boolean
created_at
string
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks webhooks:manage, or url or events was sent and the token lacks the ability that reads one of the endpoint's events. The message names it.
not_found: no such webhook endpoint.
validation_error: a field is missing or invalid; fields says which.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X PATCH https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"events": [
"customer.live",
"customer.failed",
"customer.cancelled"
]
}'$client = new GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'events' => [
'customer.live',
'customer.failed',
'customer.cancelled',
],
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"events": [
"customer.live",
"customer.failed",
"customer.cancelled"
]
}),
});
const data = await response.json();import os
import requests
response = requests.patch(
"https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"events": [
"customer.live",
"customer.failed",
"customer.cancelled"
]
},
)
data = response.json(){
"id": "whe_01jd1f4c8m2p0r6t9w3y5a7c1e",
"object": "webhook_endpoint",
"url": "https://api.acme.example/hooks/monotree",
"description": "Back office, production",
"events": [
"customer.live",
"customer.failed"
],
"active": true,
"paused_at": "2026-11-12T09:41:00Z",
"paused_reason": "manual",
"secret": "string",
"previous_secret_expires_at": "2026-11-12T09:41:00Z",
"failed_24h": 0,
"last_delivery": {
"id": "whd_01jd1g2h3j4k5m6n7p8q9r0s1t",
"status": "delivered",
"response_code": 200,
"created_at": "2026-11-12T09:42:18Z"
},
"sandbox": false,
"created_at": "2026-11-10T14:05:00Z"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Delete a webhook endpoint
/webhooks/{webhook}
webhooks:manage Removes the endpoint and its delivery log. Events that happen from now on are no longer sent to it; they stay in List events. A token only finds an endpoint whose events it may all read (the types it is subscribed to and the types among its deliveries); any other endpoint answers 404: see Which endpoints a token sees.
Parameters
webhook
required
string · path
whe_…).
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such webhook endpoint.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X DELETE https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.delete(
"https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json()Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Send a test event
/webhooks/{webhook}/test
webhooks:manage Sends a ping event to the endpoint at once and answers with the delivery: its status, your server's response_code and response_body. A failed test is not retried. At most 10 test events and redeliveries a minute to one endpoint. A token only finds an endpoint whose events it may all read (the types it is subscribed to and the types among its deliveries); any other endpoint answers 404: see Which endpoints a token sees.
Parameters
webhook
required
string · path
whe_…).
Accepts an optional Idempotency-Key header to make a retry safe.
Response · 202 The delivery.
id
string
object
string
event_id
string
id of the event that was sent.
event
string
status
string
pending waiting for its first try · delivered your server answered 2xx · retrying a try failed and another is planned at next_attempt_at · failed given up after six tries.
one of pending, delivered, retrying, failed
attempts
integer
redeliveries says how often that happened.
redeliveries
integer
response_code
integer, nullable
duration_ms
integer, nullable
next_attempt_at
string, nullable
delivered_at
string, nullable
created_at
string
payload
object
id
string
Monotree-Event-Id header. Keep it to skip repeats.
object
string
type
string
api_version
string
data is written in; also in the Monotree-Api-Version header.
created_at
string
sandbox
boolean
actor
object, nullable
user), an API token (token, named API · <token name>) or Monotree itself (system). On support events also the assistant (assistant), and on support.message.received the person at the customer who wrote (customer).
type
string
one of user, token, system, assistant, customer
name
string
data
object
customer (the whole customer right after the event) and details. For a seller event: seller, always without two_factor, passkeys and last_login_at. The Event types guide says what each type carries.
response_body
string, nullable
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such webhook endpoint.
idempotency_in_progress: a call with the same Idempotency-Key is still running.
idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: more than 10 test events and redeliveries to this endpoint in a minute, or over the general limit. Wait for the number of seconds in Retry-After.
curl -X POST https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/test \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/test', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/test', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/test",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "whd_01jd1g2h3j4k5m6n7p8q9r0s1t",
"object": "webhook_delivery",
"event_id": "evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
"event": "customer.live",
"status": "delivered",
"attempts": 1,
"redeliveries": 0,
"response_code": 200,
"duration_ms": 182,
"next_attempt_at": null,
"delivered_at": "2026-11-12T09:42:18Z",
"created_at": "2026-11-12T09:42:18Z",
"payload": {
"id": "evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
"object": "event",
"type": "customer.live",
"api_version": "1.0.0",
"created_at": "2026-11-12T09:42:18Z",
"sandbox": false,
"actor": {
"type": "system",
"name": "Monotree"
},
"data": {
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"external_ref": "org_48213"
},
"details": {
"url": "https://boulangeriemartin.monotree.com",
"admin_email": "claire@boulangeriemartin.example"
}
}
},
"response_body": "string"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Rotate the signing secret
/webhooks/{webhook}/rotate-secret
webhooks:manage Gives the endpoint a new signing secret, in the answer to this call only. The secret before it stays valid
for expire_previous_in seconds: until then every event is signed with both (two v1 values in
Monotree-Signature), so your server keeps accepting events while you move it to the new secret.
A token only finds an endpoint whose events it may all read; any other endpoint answers 404
(Which endpoints a token sees): a secret is not rotated by a token that
may not read what the secret signs.
Parameters
webhook
required
string · path
whe_…).
Accepts an optional Idempotency-Key header to make a retry safe.
Request body
expire_previous_in
integer
0 to stop it at once.
from 0 · up to 604800 · default 86400
Response · 200 The endpoint, with its new secret.
id
string
object
string
url
string
description
string, nullable
events
array of strings
* for all.
active
boolean
paused_at
string, nullable
paused_reason
string, nullable
manual: paused by you. failing: paused by Monotree after 5 days of nothing but failed deliveries, at least 20 of them.
one of manual, failing
secret
string
whsec_…). Only in the answers to Add a webhook endpoint and Rotate the signing secret.
previous_secret_expires_at
string, nullable
failed_24h
integer
failed in the last 24 hours.
last_delivery
object, nullable
id
string
status
string
one of pending, delivered, retrying, failed
response_code
integer, nullable
created_at
string
sandbox
boolean
created_at
string
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such webhook endpoint.
idempotency_in_progress: a call with the same Idempotency-Key is still running.
validation_error: a field is missing or invalid; fields says which. idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: more than 10 rotations in an hour for this endpoint, or over the general limit. Wait for the number of seconds in Retry-After.
curl -X POST https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/rotate-secret \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"expire_previous_in": 3600
}'$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/rotate-secret', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'expire_previous_in' => 3600,
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/rotate-secret', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"expire_previous_in": 3600
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/rotate-secret",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"expire_previous_in": 3600
},
)
data = response.json(){
"id": "whe_01jd1f4c8m2p0r6t9w3y5a7c1e",
"object": "webhook_endpoint",
"url": "https://api.acme.example/hooks/monotree",
"description": "Back office, production",
"events": [
"customer.live",
"customer.failed"
],
"active": true,
"paused_at": "2026-11-12T09:41:00Z",
"paused_reason": "manual",
"secret": "string",
"previous_secret_expires_at": "2026-11-12T09:41:00Z",
"failed_24h": 0,
"last_delivery": {
"id": "whd_01jd1g2h3j4k5m6n7p8q9r0s1t",
"status": "delivered",
"response_code": 200,
"created_at": "2026-11-12T09:42:18Z"
},
"sandbox": false,
"created_at": "2026-11-10T14:05:00Z"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
List deliveries
/webhooks/{webhook}/deliveries
webhooks:manage The deliveries to the endpoint, newest first, with the status code your server answered. A delivery is one event sent to one endpoint, with all its tries. Deliveries are kept for 30 days. Ask for one delivery to see the body sent and your server's answer. A token only finds an endpoint whose events it may all read (the types it is subscribed to and the types among its deliveries); any other endpoint answers 404: see Which endpoints a token sees.
Parameters
webhook
required
string · path
whe_…).
status
string · query
failed ones gave up after six tries, retrying ones have a try planned at next_attempt_at.
one of pending, delivered, retrying, failed
event_id
string · query
evt_…), to see whether and how one event reached the endpoint.
event
string · query
limit
integer · query
default 25 · up to 100
cursor
string · query
next_cursor of the page before, for the next page. Send the same filters with it.
Response · 200 A page of deliveries.
object
string
has_more
boolean
next_cursor
string, nullable
cursor for the next page.
data
array of objects
Errors
invalid_cursor: the cursor is not one this API gave out.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such webhook endpoint.
validation_error: a field is missing or invalid; fields says which.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"object": "list",
"has_more": false,
"next_cursor": "string",
"data": [
{
"id": "whd_01jd1g2h3j4k5m6n7p8q9r0s1t",
"object": "webhook_delivery",
"event_id": "evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
"event": "customer.live",
"status": "delivered",
"attempts": 1,
"redeliveries": 0,
"response_code": 200,
"duration_ms": 182,
"next_attempt_at": null,
"delivered_at": "2026-11-12T09:42:18Z",
"created_at": "2026-11-12T09:42:18Z",
"payload": {
"id": "evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
"object": "event",
"type": "customer.live",
"api_version": "1.0.0",
"created_at": "2026-11-12T09:42:18Z",
"sandbox": false,
"actor": {
"type": "system",
"name": "Monotree"
},
"data": {
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"external_ref": "org_48213"
},
"details": {
"url": "https://boulangeriemartin.monotree.com",
"admin_email": "claire@boulangeriemartin.example"
}
}
},
"response_body": "string"
}
]
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Redeliver failed deliveries
/webhooks/{webhook}/deliveries/redeliver-failed
webhooks:manage Queues the endpoint's failed deliveries of the last 24 hours again, up to 100, for example after your server was down. Each starts over as with Redeliver a delivery, but is sent from the queue rather than at once. A token only finds an endpoint whose events it may all read (the types it is subscribed to and the types among its deliveries); any other endpoint answers 404: see Which endpoints a token sees.
Parameters
webhook
required
string · path
whe_…).
Accepts an optional Idempotency-Key header to make a retry safe.
Response · 202 The deliveries queued again, `pending`.
object
string
has_more
boolean
next_cursor
string, nullable
cursor for the next page.
data
array of objects
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such webhook endpoint.
endpoint_paused: the endpoint is paused; switch it on first. idempotency_in_progress: a call with the same Idempotency-Key is still running.
idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: more than 10 of these calls in an hour for this endpoint, or over the general limit. Wait for the number of seconds in Retry-After.
curl -X POST https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/redeliver-failed \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/redeliver-failed', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/redeliver-failed', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/redeliver-failed",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"object": "list",
"has_more": false,
"next_cursor": "string",
"data": [
{
"id": "whd_01jd1g2h3j4k5m6n7p8q9r0s1t",
"object": "webhook_delivery",
"event_id": "evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
"event": "customer.live",
"status": "delivered",
"attempts": 1,
"redeliveries": 0,
"response_code": 200,
"duration_ms": 182,
"next_attempt_at": null,
"delivered_at": "2026-11-12T09:42:18Z",
"created_at": "2026-11-12T09:42:18Z",
"payload": {
"id": "evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
"object": "event",
"type": "customer.live",
"api_version": "1.0.0",
"created_at": "2026-11-12T09:42:18Z",
"sandbox": false,
"actor": {
"type": "system",
"name": "Monotree"
},
"data": {
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"external_ref": "org_48213"
},
"details": {
"url": "https://boulangeriemartin.monotree.com",
"admin_email": "claire@boulangeriemartin.example"
}
}
},
"response_body": "string"
}
]
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Get a delivery
/webhooks/{webhook}/deliveries/{delivery}
webhooks:manage One delivery, with the body sent (payload) and the first 2,000 bytes of your server's last answer (response_body). A token only finds an endpoint whose events it may all read (the types it is subscribed to and the types among its deliveries); any other endpoint answers 404: see Which endpoints a token sees.
Parameters
webhook
required
string · path
whe_…).
delivery
required
string · path
whd_…), as sent in the Monotree-Delivery header.
Response · 200 The delivery.
id
string
object
string
event_id
string
id of the event that was sent.
event
string
status
string
pending waiting for its first try · delivered your server answered 2xx · retrying a try failed and another is planned at next_attempt_at · failed given up after six tries.
one of pending, delivered, retrying, failed
attempts
integer
redeliveries says how often that happened.
redeliveries
integer
response_code
integer, nullable
duration_ms
integer, nullable
next_attempt_at
string, nullable
delivered_at
string, nullable
created_at
string
payload
object
id
string
Monotree-Event-Id header. Keep it to skip repeats.
object
string
type
string
api_version
string
data is written in; also in the Monotree-Api-Version header.
created_at
string
sandbox
boolean
actor
object, nullable
user), an API token (token, named API · <token name>) or Monotree itself (system). On support events also the assistant (assistant), and on support.message.received the person at the customer who wrote (customer).
type
string
one of user, token, system, assistant, customer
name
string
data
object
customer (the whole customer right after the event) and details. For a seller event: seller, always without two_factor, passkeys and last_login_at. The Event types guide says what each type carries.
response_body
string, nullable
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such webhook endpoint or delivery.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/whd_01jd1g2h3j4k5m6n7p8q9r0s1t \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/whd_01jd1g2h3j4k5m6n7p8q9r0s1t', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/whd_01jd1g2h3j4k5m6n7p8q9r0s1t', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/whd_01jd1g2h3j4k5m6n7p8q9r0s1t",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "whd_01jd1g2h3j4k5m6n7p8q9r0s1t",
"object": "webhook_delivery",
"event_id": "evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
"event": "customer.live",
"status": "delivered",
"attempts": 1,
"redeliveries": 0,
"response_code": 200,
"duration_ms": 182,
"next_attempt_at": null,
"delivered_at": "2026-11-12T09:42:18Z",
"created_at": "2026-11-12T09:42:18Z",
"payload": {
"id": "evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
"object": "event",
"type": "customer.live",
"api_version": "1.0.0",
"created_at": "2026-11-12T09:42:18Z",
"sandbox": false,
"actor": {
"type": "system",
"name": "Monotree"
},
"data": {
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"external_ref": "org_48213"
},
"details": {
"url": "https://boulangeriemartin.monotree.com",
"admin_email": "claire@boulangeriemartin.example"
}
}
},
"response_body": "string"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Redeliver a delivery
/webhooks/{webhook}/deliveries/{delivery}/redeliver
webhooks:manage Sends the delivery again at once and answers with how it went. Works on failed deliveries and on delivered ones, to try a fix on your side. The delivery starts over: same delivery ID, same body and event id, attempts from 0, and the usual retries if this try fails. A retry that was planned is replaced, not added to. Refused while the endpoint is paused or a try is being sent. At most 10 redeliveries and test events a minute to one endpoint. A token only finds an endpoint whose events it may all read (the types it is subscribed to and the types among its deliveries); any other endpoint answers 404: see Which endpoints a token sees. The token must be able to read the delivery's event type.
Parameters
webhook
required
string · path
whe_…).
delivery
required
string · path
whd_…), as sent in the Monotree-Delivery header.
Accepts an optional Idempotency-Key header to make a retry safe.
Response · 202 The delivery, after the try.
id
string
object
string
event_id
string
id of the event that was sent.
event
string
status
string
pending waiting for its first try · delivered your server answered 2xx · retrying a try failed and another is planned at next_attempt_at · failed given up after six tries.
one of pending, delivered, retrying, failed
attempts
integer
redeliveries says how often that happened.
redeliveries
integer
response_code
integer, nullable
duration_ms
integer, nullable
next_attempt_at
string, nullable
delivered_at
string, nullable
created_at
string
payload
object
id
string
Monotree-Event-Id header. Keep it to skip repeats.
object
string
type
string
api_version
string
data is written in; also in the Monotree-Api-Version header.
created_at
string
sandbox
boolean
actor
object, nullable
user), an API token (token, named API · <token name>) or Monotree itself (system). On support events also the assistant (assistant), and on support.message.received the person at the customer who wrote (customer).
type
string
one of user, token, system, assistant, customer
name
string
data
object
customer (the whole customer right after the event) and details. For a seller event: seller, always without two_factor, passkeys and last_login_at. The Event types guide says what each type carries.
response_body
string, nullable
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such webhook endpoint or delivery.
endpoint_paused: the endpoint is paused; switch it on first. delivery_in_progress: a try of this delivery is being sent right now. idempotency_in_progress: a call with the same Idempotency-Key is still running.
idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: more than 10 redeliveries and test events to this endpoint in a minute, or over the general limit. Wait for the number of seconds in Retry-After.
curl -X POST https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/whd_01jd1g2h3j4k5m6n7p8q9r0s1t/redeliver \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/whd_01jd1g2h3j4k5m6n7p8q9r0s1t/redeliver', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/whd_01jd1g2h3j4k5m6n7p8q9r0s1t/redeliver', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/webhooks/whe_01jd1f4c8m2p0r6t9w3y5a7c1e/deliveries/whd_01jd1g2h3j4k5m6n7p8q9r0s1t/redeliver",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"id": "whd_01jd1g2h3j4k5m6n7p8q9r0s1t",
"object": "webhook_delivery",
"event_id": "evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
"event": "customer.live",
"status": "delivered",
"attempts": 1,
"redeliveries": 0,
"response_code": 200,
"duration_ms": 182,
"next_attempt_at": null,
"delivered_at": "2026-11-12T09:42:18Z",
"created_at": "2026-11-12T09:42:18Z",
"payload": {
"id": "evt_01jcz8wg4h7v3y6n9q2k5m8p1r",
"object": "event",
"type": "customer.live",
"api_version": "1.0.0",
"created_at": "2026-11-12T09:42:18Z",
"sandbox": false,
"actor": {
"type": "system",
"name": "Monotree"
},
"data": {
"customer": {
"id": "cus_01jcz8w3k1x9q2v7s4e6m0b5n8",
"object": "customer",
"status": "live",
"company_name": "Boulangerie Martin",
"company_id": "boulangeriemartin",
"external_ref": "org_48213"
},
"details": {
"url": "https://boulangeriemartin.monotree.com",
"admin_email": "claire@boulangeriemartin.example"
}
}
},
"response_body": "string"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.