Webhooks

6 calls. Every request needs the Authorization header: see the overview.

`webhooks.list`

GET /web-hooks

Every registration (header values masked as "********").

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Response: WebHookRegistration[] (200)

curl -X GET "https://api.maitento.com/web-hooks" \
  -H "Authorization: $MAITENTO_AUTH"

const hooks = await mt.webhooks.list();

mt.webhooks.list()

`webhooks.create`

POST /web-hooks

Registers a URL for one entity type (one registration per URL and type).

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Request body: WebHookRegistrationCreateRequest

Field	Type	Required	Description
`type`	`WebHookType`	yes	What the web hook reports on.
`url`	`string`	yes	The URL to call.
`secret`	`string`	yes	A secret of your choosing that every call is signed with (`X-MT-WebHook-Signature`, an HMAC-SHA256 of `X-MT-WebHook-Timestamp` and the body), so your endpoint can check the call came from Maitento. It’s never sent itself. Write-only.
`headers`	`map<string, string>`	yes	Extra HTTP headers to send with every call (`{}` for none). Values are write-only.

Response: WebHookRegistration (200)

curl -X POST "https://api.maitento.com/web-hooks" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"type":"AppProcess","url":"...","secret":"...","headers":{}}'

await mt.webhooks.create({ type: "InteractionProcess", url: "https://example.com/maitento/webhook", secret: process.env.WEBHOOK_SECRET! });

mt.webhooks.create(type="InteractionProcess", url="https://example.com/maitento/webhook", secret=os.environ["WEBHOOK_SECRET"])

`webhooks.delete`

DELETE /web-hooks/by-id/{id}

Deletes a registration.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Response: no body (200)

curl -X DELETE "https://api.maitento.com/web-hooks/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.webhooks.delete("0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d");

mt.webhooks.delete("1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d")

`webhooks.get`

GET /web-hooks/by-id/{id}

The registration with this id. Throws NotFoundError when there is none.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Response: WebHookRegistration (200)

curl -X GET "https://api.maitento.com/web-hooks/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

const hook = await mt.webhooks.get("0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d");

mt.webhooks.get("1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d")

`webhooks.update`

PUT /web-hooks/by-id/{id}

Changes the URL, secret or headers. headers is the full set: a missing name is removed, null or "********" keeps a stored value. Moving the URL to another origin needs the secret again. signedOnly: true stops a web hook registered before deliveries were signed from sending its secret in X-MT-WebHook-Secret: from then on its deliveries are only signed. It can’t be undone, so set it once your receiver checks X-MT-WebHook-Signature. false or leaving it out changes nothing.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: WebHookRegistrationUpdateRequest

Field	Type	Required	Description
`url`	`string`	yes	The URL to call.
`secret`	`string \| null`		A new secret to sign calls with (`X-MT-WebHook-Signature`). Null or omitted: the stored secret is kept.
`headers`	`map<string, string \| null> \| null`		The complete set of headers the web hook has after the update: a name left out is removed, and `{}` clears them all. Values are write-only (responses show `******`), so a value of `null` or `******` keeps the stored value for that name; any other string replaces it. Omitting `headers` (or sending `null`) leaves every header unchanged.
`signedOnly`	`boolean \| null`		True stops a web hook registered before deliveries were signed from sending its secret in `X-MT-WebHook-Secret`: from then on its deliveries are only signed, like every web hook registered now. It can’t be undone, so false or omitted changes nothing.

Response: WebHookRegistration (200)

curl -X PUT "https://api.maitento.com/web-hooks/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"url":"..."}'

await mt.webhooks.update("0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", { url: "https://example.com/maitento/webhook-v2" });

mt.webhooks.update("1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", url="https://example.com/maitento/webhook-v2")

`webhooks.deliveries`

GET /web-hooks/by-id/{id}/deliveries

The registration’s delivery log (sent deliveries are kept a day, permanent failures a week).

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`limit`	`integer`

Response: WebHookDelivery[] (200)

curl -X GET "https://api.maitento.com/web-hooks/by-id/<id>/deliveries" \
  -H "Authorization: $MAITENTO_AUTH"

const deliveries = await mt.webhooks.deliveries("0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", { limit: 50 });

mt.webhooks.deliveries("1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", limit=20)