Webhooks

Update a webhook endpoint

Changes apply to events from now on, and to deliveries still waiting for a retry: each is checked against the endpoint as it is when its turn comes. A delivery whose event the endpoint no longer takes (its new types or profiles) ends unsent, with endpoint_changed on its attempt; the ones it still takes go to its new url. A new url starts with a closed breaker, makes the caller (or the person behind the API key or agent) the person it sends for (so does any change to one that sends for nobody, onBehalfOf null), and the deliveries it had already tried or held at the old address end with endpoint_changed (replay them to send them to the new one). enabled false stops it, and its waiting deliveries end at once with endpoint_disabled; true starts it again for new events, also after a 410 Gone or days of failures, with its failures forgotten. What ended while it was off is not sent by itself: replay it (Replay an endpoint's deliveries).

patch/webhooks/{id}

Request

  • Base URL
    https://api.rizamo.com/v1
  • Auth
    HTTP bearer

Path parameters

idstring required

The webhook endpoint's id (wh_).

Request body

urlstring

Where Rizamo sends events: an https address on the public internet.

descriptionstring

What it is for, for the people of the team.

eventsWebhookEventType[] nullable

The event types it receives. Null: every type, those Rizamo adds later included. A key or agent lists the inbox's types (comment.received, message.received, message.sent) only with inbox:read, and comment_automation.* only with automations:read; with null, the endpoint gets none of those it cannot read.

profileIdsstring[] nullable

Only events of these profiles. Null: every profile's, and the events of no profile. Someone limited to some profiles gives some of theirs.

enabledboolean

false stops it; true starts it again, also after a 410 Gone or days of failures.

Response

OK

idstring required
urlstring uri required
descriptionstring required
eventsWebhookEventType[] nullable required

The event types it receives. Null: every type, those Rizamo adds later included. The inbox's (comment.received, message.received, message.sent) and comment automations' (comment_automation.*) carry what people wrote: an endpoint a key or agent made, or last pointed at its url, gets them only if it had inbox:read (automations:read for automations), whatever this lists.

profileIdsstring[] nullable required

Only events of these profiles, and of those only the ones its person reaches now (onBehalfOf). Null: every profile's, and the events of no profile. Empty once every profile it was limited to is deleted: it is then disabled. Someone limited to some profiles only sees and makes endpoints within them.

status'active' | 'failing' | 'disabled' required

active: sends, and its last attempt was delivered (or none was made yet). failing: sends, but its last attempt failed; after 10 failures in a row its deliveries wait while one at a time tries it (breaker). disabled: sends nothing, see disabledReason.

disabledReason'by_request' | 'gone' | 'failing' | 'profile_deleted' nullable required

by_request: someone set enabled to false. gone: the endpoint answered 410 Gone. failing: its breaker was open and nothing got through for 5 days; for these two Rizamo emails the team's owners and editors. profile_deleted: every profile it was limited to was deleted, which leaves profileIds empty; give it profiles to enable it again. Null while it sends.

breaker'closed' | 'open' required

open: it failed 10 times in a row, so its deliveries wait and one at a time tries it every 15 minutes; the first one delivered, or a test that gets through, sends the rest. closed: deliveries go as they come. A new url starts closed.

failingSincestring date-time nullable required

Its first failed attempt of the failures in a row (failures hours apart, further than the retries' spacing, start anew). Null once an attempt is delivered.

disablesAtstring date-time nullable required

When Rizamo disables it unless an attempt is delivered first: failingSince and 5 days, while its breaker is open. Null otherwise.

successRatenumber nullable required

Of the attempts in the last 7 days, the percent delivered (a 2xx answer). Null with none.

lastDeliveryAtstring date-time nullable required

When Rizamo last tried to deliver to it, whatever the answer.

createdAtstring date-time required
updatedAtstring date-time required

Changes

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