Webhooks
Where an organization's webhook events are delivered, and how reliably: its endpoints, every event recorded, every delivery made, to an endpoint or as a notification email, and the reliability report that keeps Mountaya's service availability apart from each endpoint's success. Every operation here needs a session token beside the key.
A webhook endpoint: a URL of the organization's own that Mountaya delivers webhook events to, signed with the endpoint's secret. The secret is answered once, by postOrganizationWebhookEndpoint, and never by a read.
idstring (uuid)
Identifier of the endpoint, the webhook_endpoint_id a delivery names.
organization_idstring (uuid)
Identifier of the organization the endpoint belongs to.
urlstring (uri)
The URL Mountaya delivers to: https, on a host that resolves to a public address, answered within 10 seconds. A redirect is never followed.
descriptionstring | null
What the endpoint is for, as the organization wrote it, null when it has none.
enabled_eventsarray of string
The event types the endpoint is sent: each a member of WebhookEventType, a family followed by .* for every type of the family, such as organization.member.*, or * for every public type, those added to the contract later included.
statusstring
One of: enabled, disabled
Whether Mountaya delivers to the endpoint.
disabled_reasonstring | null
One of: requested, failing
Why the endpoint is disabled, null while it is enabled.
disabled_atstring (date-time) | null
When the endpoint was disabled, null while it is enabled.
failing_sincestring (date-time) | null
When the endpoint's run of failed deliveries began, null while its last delivery succeeded. At 24 hours Mountaya records organization.webhook_endpoint.failing and emails the organization's owners and admins; at 72 hours it disables the endpoint. A delivery that succeeds after the run was reported records organization.webhook_endpoint.recovered. Read it before enabling a disabled endpoint again, which clears it, to redeliver from it.
etagstring
The version of the endpoint, the one the ETag of a read of it carries, opaque and compared whole. It moves on every change to the endpoint's configuration and status, and never with its health: a delivery failing or succeeding again moves failing_since and leaves it as it is. Send it as If-Match to make patchOrganizationWebhookEndpoint or deleteOrganizationWebhookEndpoint conditional.
created_byRelationToUser | null
The member who created the endpoint, null when their account has been deleted.
created_atstring (date-time)
When the endpoint was created.
updated_atstring (date-time)
When the endpoint's configuration or status last changed. Its health, failing_since, does not move it.
/v1/organizations/{organization_id}/webhook-endpointsReturns the organization's webhook endpoints, enabled and disabled, each with the event types it is sent, its status and when its run of failed deliveries began. A secret is never answered: postOrganizationWebhookEndpoint answers it once.
- A session token minted for
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. - The listing is paged, 50 endpoints a page unless
limitsays otherwise, oldest first. An organization holds 2 unless its agreement says otherwise, 6 at most, so one page holds them all. Send the page'snext_cursorback ascursorfor the next one; the last page reportsnext_cursor: null.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Query parameters
cursorstring
in query
Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.
limitinteger (int32)
in query
default: 50
How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.
Response 200
One page of the organization's webhook endpoints, oldest first. extensions.metadata.pagination.next_cursor asks for the next page, and is null on the last.
extensionsobject
The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination alone: the limit this page was served at, and the next_cursor of the page after it, null on the last.
dataarray of WebhookEndpoint
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/webhook-endpointsCreates an endpoint Mountaya delivers the organization's webhook events to: every event of a type its enabled_events names, from the next one recorded on, signed with a secret of its own, answered here once. A create sent twice without an Idempotency-Key makes two endpoints; with one, the second is not answered the first one's endpoint, since that answer carried the secret and is never kept: it is the 409 coded IDEMPOTENCY_ANSWER_UNAVAILABLE. A create sent again with the key, after the first failed with a 5xx once the endpoint was made, is that 409 too, whose extensions.metadata.location names the endpoint made, /v1/organizations/{organization_id}/webhook-endpoints/{webhook_endpoint_id}. This API answers a secret once: an owner or an admin reads that endpoint's again in Mountaya's web application, or deletes it and creates another.
- Owner or admin only (403 otherwise).
urlishttps, written in printable ASCII, at most 2048 characters, with no credentials before its host and no fragment, its host, port included, at most 259 characters; and that host resolves to a public address: a private, loopback or link-local one is a400namingurl, and so is one Mountaya cannot resolve. A redirect is never followed.enabled_eventsnames types, families followed by.*, or*. A type or a family the contract does not publish is a400naming its position;getWebhookEventTypeslists them.- An organization holds 2 endpoints, enabled and disabled, unless its agreement says otherwise, 6 at most: one more is refused at
webhook-endpoints, a429codedLIMIT_REACHEDwith noRetry-After. Delete one first, or agree a higher limit. An organization whose limit was lowered below what it holds keeps its endpoints, and creates none until it holds fewer than the limit. - It is limited, together with the organization's other endpoint writes this document's introduction lists, to 30 a minute per user and then 300 a minute per organization; past either, the answer is a
429carryingRetry-After, and nothing is done. - Mountaya delivers each event at least once, in no promised order, retrying a failed attempt for about 72 hours. This document's introduction says how a delivery is signed, retried and recorded.
Webhook events organization.webhook_endpoint.created, recorded by the task organization.webhook_endpoint.create.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
Body
Where to deliver, and which event types.
urlstring (uri)
in body
The URL Mountaya delivers to. It is https, written in printable ASCII, at most 2048 characters, with no credentials before its host and no fragment, its host, port included, at most 259 characters; and that host resolves to a public address: a private, loopback or link-local one is a 400 naming url, and so is one that cannot be resolved.
descriptionstring
in body
What the endpoint is for, at most 100 characters, trimmed. Omitted, the endpoint has none.
enabled_eventsarray of string
in body
The event types the endpoint is sent: each a member of WebhookEventType, a family followed by .*, or * for every public type, those added later included. A type or a family the contract does not publish is a 400 naming its position.
Response 201
The endpoint as created, with its secret, shown here once. Location names it, /v1/organizations/{organization_id}/webhook-endpoints/{webhook_endpoint_id}, the path getOrganizationWebhookEndpoint reads it at.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataWebhookEndpointWithSecret
A webhook endpoint as postOrganizationWebhookEndpoint answers it: the endpoint, and the secret its deliveries are signed with. This is the one answer that carries the secret, and it is never kept for the request's Idempotency-Key, so store it before anything else.
Errors 400, 401, 403, 404, 409, 413, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/webhook-endpoints/{webhook_endpoint_id}Returns one of the organization's webhook endpoints, as getOrganizationWebhookEndpoints lists it. Its secret is never answered.
- A session token minted for
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. - The answer's
ETagis the endpoint'setag. Send it asIf-MatchonpatchOrganizationWebhookEndpointordeleteOrganizationWebhookEndpointto make the change conditional on nobody having changed the endpoint since.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
webhook_endpoint_idstring (uuid)
in path
Identifier of the webhook endpoint, the id a WebhookEndpoint carries. One that names no endpoint of the organization, another organization's included, is answered 404, so an endpoint id cannot be probed here.
Response 200
The endpoint, without its secret.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataWebhookEndpoint
A webhook endpoint: a URL of the organization's own that Mountaya delivers webhook events to, signed with the endpoint's secret. The secret is answered once, by postOrganizationWebhookEndpoint, and never by a read.
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/webhook-endpoints/{webhook_endpoint_id}Changes an endpoint's URL, description, event types or status. Each field is optional and an omitted one keeps its value; enabled_events is replaced whole. An empty object changes nothing and answers the endpoint as it stands.
- Owner or admin only (403 otherwise).
urlandenabled_eventsare held to the rules of a new endpoint's, and refused the same way.statusdisabledstops every delivery to the endpoint, the ones still retrying included, which endcanceled.enabledstarts them again from the next event recorded, and clearsfailing_since; the events recorded while it was disabled are not sent on their own, andpostOrganizationWebhookDeliveryredelivers those of the last 30 days.- The secret is not changed here.
If-Matchmakes the change conditional: send the endpoint'setag, and an endpoint changed since is refused with412, changing nothing.- It is limited, together with the organization's other endpoint writes this document's introduction lists, to 30 a minute per user and then 300 a minute per organization; past either, the answer is a
429carryingRetry-After, and nothing is done.
Webhook events organization.webhook_endpoint.updated, organization.webhook_endpoint.enabled, organization.webhook_endpoint.disabled, recorded by the task organization.webhook_endpoint.update.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
webhook_endpoint_idstring (uuid)
in path
Identifier of the webhook endpoint, the id a WebhookEndpoint carries. One that names no endpoint of the organization, another organization's included, is answered 404, so an endpoint id cannot be probed here.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
If-Matchstring
in header
Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.
Body
What to change. Send only what is changing.
urlstring (uri)
in body
The URL Mountaya delivers to from the next delivery on, held to the rules of a new endpoint's. A delivery still retrying is sent to it.
descriptionstring | null
in body
What the endpoint is for, at most 100 characters, trimmed. null clears it.
enabled_eventsarray of string
in body
The event types the endpoint is sent, replacing the list whole, as a new endpoint's. The list is read when an event is handed to its deliveries, a moment after it is recorded: an event recorded just before the change may be delivered by either list, and every later one by the new.
statusstring
in body
One of: enabled, disabled
disabled stops every delivery to the endpoint, those still retrying included, with disabled_reason requested; enabled starts them again from the next event, and clears failing_since. The events recorded meanwhile are not sent on their own: postOrganizationWebhookDelivery redelivers them.
Response 200
The endpoint after the change, without its secret.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataWebhookEndpoint
A webhook endpoint: a URL of the organization's own that Mountaya delivers webhook events to, signed with the endpoint's secret. The secret is answered once, by postOrganizationWebhookEndpoint, and never by a read.
Errors 400, 401, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/webhook-endpoints/{webhook_endpoint_id}Deletes an endpoint: nothing is delivered to it from then on, and its deliveries still retrying end canceled. Its deliveries already made stay readable for the 13 months deliveries are kept, and getOrganizationWebhookDeliveries and getOrganizationWebhookHealth still narrow to it by its identifier. It frees its place under the organization's webhook-endpoints limit.
- Owner or admin only (403 otherwise).
- An endpoint already deleted is a
404; a delete retried with the first one'sIdempotency-Keyis answered its first200. If-Matchmakes the deletion conditional: send the endpoint'setag, and an endpoint changed since is refused with412, deleting nothing.- It is limited, together with the organization's other endpoint writes this document's introduction lists, to 30 a minute per user and then 300 a minute per organization; past either, the answer is a
429carryingRetry-After, and nothing is done.
Webhook events organization.webhook_endpoint.deleted, recorded by the task organization.webhook_endpoint.delete.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
webhook_endpoint_idstring (uuid)
in path
Identifier of the webhook endpoint, the id a WebhookEndpoint carries. One that names no endpoint of the organization, another organization's included, is answered 404, so an endpoint id cannot be probed here.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
If-Matchstring
in header
Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.
Response 200
The endpoint is deleted. There is no payload.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Errors 400, 401, 403, 404, 409, 412, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/webhook-eventsReturns every public webhook event recorded in the organization over the 13 months events are kept, whether or not an endpoint was sent it: what its members' acts and Mountaya recorded, before any endpoint subscribes. Each is the envelope a delivery carries, exactly. It is how a receiver that was down past the retries reconciles: list from the last event it processed, and redeliver or read what it missed.
- A session token minted for
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. - The filters combine.
typekeeps one type andfamilyevery type of one family;related_object_idthe events about one object;request_idthe events one API request recorded, by theX-Request-Idits answer carried;actor_typeandactor_user_idwho made the change;delivery_outcomethe events with at least one delivery standing so;start_atandend_atwhen they were recorded. - The listing is paged, 50 events a page unless
limitsays otherwise, the most recent first. Send the page'snext_cursorback ascursorfor the next one; the last page reportsnext_cursor: null. - An event is listed within seconds of its change.
getOrganizationWebhookEventreads one with its deliveries.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Query parameters
cursorstring
in query
Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.
limitinteger (int32)
in query
default: 50
How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.
typestring
in query
Keep only the events of this type.
familystring
in query
Keep only the events of this family, every type of it: organization.member keeps organization.member.created, .updated and .deleted. A family the contract does not publish is a 400.
related_object_idstring
in query
Keep only the events about this object, the related_object.id they carry: a UUID, or an invoice's or a payment method's identifier.
request_idstring
in query
Keep only the events this API request recorded: the X-Request-Id its answer carried, 32 lowercase hexadecimal characters.
actor_typestring
in query
One of: user, key, mountaya
Keep only the events this kind of actor made.
actor_user_idstring (uuid)
in query
Keep only the events this person made.
delivery_outcomestring
in query
One of: pending, retrying, succeeded, exhausted, canceled
Keep only the events with at least one delivery standing so: exhausted lists what an endpoint never received.
start_atstring (date-time)
in query
The first instant covered, inclusive, as an RFC 3339 date-time. Events and deliveries are kept 13 months, so an instant before that covers nothing more. A start_at after end_at is a 400 naming both.
end_atstring (date-time)
in query
The instant the range ends at, exclusive, as an RFC 3339 date-time. Omitted, the range runs to the moment the request is answered.
Response 200
One page of the organization's webhook events, the most recent first. extensions.metadata.pagination.next_cursor asks for the next page, and is null on the last.
extensionsobject
The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination alone: the limit this page was served at, and the next_cursor of the page after it, null on the last.
dataarray of WebhookEvent
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/webhook-events/{event_id}Returns one webhook event, the envelope its deliveries carried, with the deliveries made of it: one per endpoint it was sent to, per notification email it caused, and per resend or redelivery since, each with its last attempt.
delivery_countis how many deliveries were made of the event, anddeliveriescarries them all up to 100. Past that it carries the 100 most recently started:getOrganizationWebhookDeliveriespages every one of them byevent_id.- A session token minted for
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. - An event is kept 13 months; one older is a
404.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
event_idstring (uuid)
in path
Identifier of the webhook event, the id a WebhookEvent carries and the Mountaya-Event-Id header of each of its deliveries. One that names no event of the organization within the 13 months events are kept is answered 404.
Response 200
The event, with its deliveries.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataWebhookEventWithDeliveries
A webhook event with the deliveries made of it: one per endpoint it was sent to, per notification email it caused, and per resend or redelivery since. An event no destination was recorded for carries none.
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/webhook-deliveriesReturns every delivery of the organization's webhook events over the 13 months deliveries are kept: to its endpoints, and the notification emails its events caused, each with where it stands and its last attempt. An email delivery names its recipient and its notification, never what the email said.
- A session token minted for
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. - The filters combine:
webhook_endpoint_idone endpoint,event_idone event,destinationendpoints or emails,outcomewhere a delivery stands,failure_classandfailure_kindhow its last attempt failed,event_typethe type delivered,trigger_idthe deliveries one resend, test or redelivery started, andstart_atandend_atwhen the deliveries started: a delivery is listed by its first attempt, wherever its later ones fall. - The listing is paged, 50 deliveries a page unless
limitsays otherwise, the most recently started first. Send the page'snext_cursorback ascursorfor the next one; the last page reportsnext_cursor: null.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Query parameters
cursorstring
in query
Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.
limitinteger (int32)
in query
default: 50
How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.
webhook_endpoint_idstring (uuid)
in query
Keep only what concerns this webhook endpoint of the organization: one it holds, or one it deleted, whose deliveries stay readable for the 13 months they are kept. One that names no endpoint the organization held in those 13 months is a 400 naming it. Omitted, every destination is covered, the notification emails included.
event_idstring (uuid)
in query
Keep only the deliveries of this event, by the id getOrganizationWebhookEvents lists: every one of them, where getOrganizationWebhookEvent carries the 100 most recently started.
destinationstring
in query
One of: endpoint, email
Keep only the deliveries to this kind of destination: email keeps the notification emails.
outcomestring
in query
One of: pending, retrying, succeeded, exhausted, canceled
Keep only the deliveries standing so.
failure_classstring
in query
One of: receiver, mountaya
Keep only the deliveries whose last attempt failed, and whose failure is this one's.
failure_kindstring
in query
One of: timeout, connection, tls, redirect, http-status, refused-address, bounced, unknown-mailbox, blocklisted, spam, internal
Keep only the deliveries whose last attempt failed this way.
event_typestring
in query
Keep only the deliveries of events of this type.
trigger_idstring (uuid)
in query
Keep only the deliveries one resend, test or redelivery started, by the id postOrganizationWebhookDelivery answered.
start_atstring (date-time)
in query
The first instant covered, inclusive, as an RFC 3339 date-time. Events and deliveries are kept 13 months, so an instant before that covers nothing more. A start_at after end_at is a 400 naming both.
end_atstring (date-time)
in query
The instant the range ends at, exclusive, as an RFC 3339 date-time. Omitted, the range runs to the moment the request is answered.
Response 200
One page of the organization's webhook deliveries, the most recently started first. extensions.metadata.pagination.next_cursor asks for the next page, and is null on the last.
extensionsobject
The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination alone: the limit this page was served at, and the next_cursor of the page after it, null on the last.
dataarray of WebhookDelivery
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/webhook-deliveriesStarts deliveries to one of the organization's endpoints, which run after the answer. The body names the endpoint and exactly one of three things:
event_id, a resend: one event recorded in the last 30 days, delivered again on the delivery schedule, whether or not the endpoint was sent it the first time.test, a test: a test event of the type named, its payload this contract's example for the type with anidof its own, delivered once without retries. It is recorded nowhere else and listed by nogetOrganizationWebhookEvents.since, a redelivery: every event recorded from that instant on, at most 30 days ago, whose type the endpoint is sent, delivered again oldest first at a paced rate. Use it after an outage outlasted the retries, or after enabling an endpoint again, from thefailing_sincethe endpoint carried before it was enabled. One redelivery runs at a time for an endpoint.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
Body
The endpoint, and the event, the test or the instant to redeliver from.
webhook_endpoint_idstring (uuid)
in body
Identifier of the endpoint to deliver to. A disabled one is a 409: enable it first.
event_idstring (uuid)
in body
A resend: the event to deliver again, recorded in the last 30 days, whether or not the endpoint was sent it the first time or its enabled_events names its type. It starts one delivery, its own attempts on the delivery schedule.
testobject
in body
A test: a test event of the type named, delivered once without retries.
sincestring (date-time)
in body
A redelivery: every event recorded from this instant on, at most 30 days ago, whose type the endpoint's enabled_events names, delivered again oldest first at a paced rate, each its own delivery carrying the redelivery's trigger_id. An instant further back, or one still to come, is a 400 naming it.
Response 202
The resend, test or redelivery started. Its deliveries run after the answer, each carrying its id as trigger_id; a resend's or a test's one delivery is delivery_id.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataWebhookDeliveryTrigger
A resend, a test or a redelivery postOrganizationWebhookDelivery started. The deliveries it starts run after the answer, and each carries its id as trigger_id, which getOrganizationWebhookDeliveries filters on.
Errors 400, 401, 403, 404, 409, 413, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/webhook-deliveries/{delivery_id}Returns one delivery with every attempt made of it: when each was due and made, how it ended and whose a failure was, and for an endpoint the status it answered and the first 2 KiB of its answer. A notification email's delivery names its recipient and its notification, never what the email said.
- A session token minted for
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. - A delivery is kept 13 months; one older is a
404.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
delivery_idstring (uuid)
in path
Identifier of the delivery, the id a WebhookDelivery carries. One that names no delivery of the organization within the 13 months deliveries are kept is answered 404.
Response 200
The delivery, with its attempts.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataWebhookDeliveryWithAttempts
A delivery with every attempt made of it, the first one first.
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/webhook-healthReturns how reliably the organization's webhook events were delivered over a window: as totals, as a series of hours or days, and one line per destination. It keeps Mountaya's service availability apart from each endpoint's success, since every failed attempt is classed as the receiver's or as Mountaya's.
- A session token minted for
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. windowasks for the last 24 hours or 7 days, an hour at a time, or the last 30 days, a day at a time, ending at the hour the request is answered in. Omitted with no range, it is24h.start_atandend_atask for a range instead, at most 92 days within the 13 months deliveries are kept: an hour at a time up to 7 days, a day at a time beyond.windowbeside either is a400.webhook_endpoint_idnarrows the report to one endpoint; omitted, it covers every endpoint and the notification emails, each a destination line of its own.availabilityis Mountaya's: the share of the attempts due that were made on schedule with no failure of Mountaya's. The success rates are the endpoints': how often a delivery succeeded at its first attempt, and at any.- The figures are a series over the window, not a listing, so they are not paged.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Query parameters
webhook_endpoint_idstring (uuid)
in query
Keep only what concerns this webhook endpoint of the organization: one it holds, or one it deleted, whose deliveries stay readable for the 13 months they are kept. One that names no endpoint the organization held in those 13 months is a 400 naming it. Omitted, every destination is covered, the notification emails included.
windowstring
in query
One of: 24h, 7d, 30d
The window to report on, ending at the hour the request is answered in. Omitted with no range, it is 24h; beside start_at or end_at it is a 400.
start_atstring (date-time)
in query
The first instant covered, inclusive, as an RFC 3339 date-time. Events and deliveries are kept 13 months, so an instant before that covers nothing more. A start_at after end_at is a 400 naming both.
end_atstring (date-time)
in query
The instant the range ends at, exclusive, as an RFC 3339 date-time. Omitted, the range runs to the moment the request is answered.
Response 200
The reliability report.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataWebhookHealth
The reliability of an organization's webhooks over a span of time: Mountaya's service availability apart from each endpoint's success, as totals, as a series of hours or days, and one line per destination. It covers the organization's endpoints and its notification emails, or one endpoint.
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/webhook-event-typesReturns every public webhook event type with its family and what records it: the members of WebhookEventType, which an endpoint's enabled_events names. The catalog is the same for every organization, and this document's webhooks describes each type's payload.
- A session token minted for
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the key's organization, and is a 403 otherwise. - The catalog is a set of a size Mountaya decides, so it is not paged.
Response 200
Every public webhook event type, ordered by type.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataarray of WebhookEventCatalogEntry
Errors 400, 401, 403, 429, 500, 504. See Errors.