Webhooks

Update a webhook

Change the endpoint, the description, the filters, or enabled. Fields you omit are left as they are; a body that names none of them is a 400.

A new url is checked exactly as on create. enabled: true clears a failing disable and starts fresh: the 24 hours before it can be disabled for failing again count from now, not from its last 2xx. Sent to a subscription that is already enabled, it does not restart them. enabled: false stops deliveries and records that you chose to. It is not a pause that holds events for later: most events while it is disabled are never queued, and a queued delivery whose next attempt falls due while it is disabled is dropped. Nor is it a clean cut: a retry that was not yet due, or an event that reaches the platform late, can still be delivered after you enable it again. Read the computer’s events_url with since= to reconcile, and dedupe on webhook-id.

While the account’s plan includes no webhooks, a body with a url or with enabled: true is a 402 and nothing changes; the description, the filters and enabled: false can still be set.

Requires the member role or higher.

patch/webhooks/{id}

Request

  • Base URL: https://app.mandala.computer/api/v1
  • URL: https://app.mandala.computer/api/v1/webhooks/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

The webhook id.

Request body

urlstring

Where to POST. https:// only, no username or password in it, at most 2048 characters — counted on the string you send, before it is parsed, so a non-ASCII character may count as two — and it must resolve to a public address — a hostname whose answers include a private, loopback, link-local or otherwise reserved address is refused, and so is a literal one. A port other than 443 is fine. The name is looked up when you send it: one that does not resolve then is a 400 (<host> did not resolve) even when the cause is a passing DNS failure, so a name you have not published yet cannot be registered, and the same request works once it resolves. What is stored is the URL as parsed: the host lower-cased, a default port dropped, and a / added to a bare origin, so compare against the stored url rather than what you sent.

descriptionstring

Free text for your listing, up to 200 characters.

eventsstring[]

Event types to deliver, from the vocabulary on Webhook. Omit or send [] for every type. An unknown type is a 400 that lists them.

computersstring[]

Computer ids to deliver for, up to 64, each a non-empty string of at most 64 characters. Omit or send [] for every computer in scope.

enabledboolean

Whether deliveries are made.

Response

The subscription as stored.

idstring required

whk- and sixteen hex characters.

urlstring required

Where deliveries are POSTed. https:// only. The URL as the platform parsed it, which can differ in spelling from what you sent: the host lower-cased, a default port dropped, a bare origin ending in /.

descriptionstring required

Free text, for your listing. Empty when you gave none.

eventsstring[] required

The event types this subscription receives. Empty means every type. The vocabulary is the event socket’s (the computer’s events_url) less file.changed: window.opened, window.closed, window.focused, window.blurred, clipboard.changed, process.exited, computer.idle, computer.ready, computer.started, computer.stopped, computer.suspended.

computersstring[] required

The computer ids this subscription receives events for. Empty means every computer in scope. Not checked against your computers when you set it — a subscription may name a computer you are about to create.

enabledboolean required

Whether deliveries are made. Set false by the platform when an endpoint has failed for a day, or when the account moves to a plan without webhooks — see disabled_reason. Back to true by you with PATCH, which starts fresh, or, for plan, by the platform when you choose a plan again, which starts fresh too.

disabled_reason'customer' | 'failing' | 'plan' | 'null' nullable required

Why enabled is false: customer when you disabled it, failing when the platform did — a delivery ran out of attempts and nothing had been accepted for 24 hours, counted from the later of the last 2xx and when the subscription was last enabled — and plan when the account moved to a plan without webhooks. A plan subscription is enabled again, oldest first, as many as the plan allows, when the account chooses a plan that includes webhooks. null while enabled.

disabled_atstring nullable required

RFC 3339 timestamp, or null while enabled.

last_success_atstring nullable required

When the endpoint last answered 2xx to any delivery. null until it has.

last_failure_atstring nullable required

When a delivery attempt last failed. null until one has.

last_statusinteger nullable required

The HTTP status of the newest attempt, whatever it was. null before any attempt, or when the newest got no answer.

workspace_idstring

The workspace this subscription is confined to. Present only when it was created with a workspace-scoped API key; absent on an account-wide subscription.

created_atstring required

RFC 3339 timestamp.

updated_atstring required

RFC 3339 timestamp.

Changes

No recorded changes to this operation across all 1 revision of this API.