API reference

Webhooks

Be called when something happens in your organization, and read the deliveries.

A webhook is a URL Rytiv calls for events of your organization. Each delivery is recorded and can be read back.

Endpoints

POST /v1/webhooks: Registers a webhook URL
GET /v1/webhooks: The organization’s webhooks
GET /v1/webhooks/:id: One webhook
GET /v1/webhooks/:id/deliveries: Its deliveries with their status
DELETE /v1/webhooks/:id: Removes the webhook

POST /v1/webhooks

Registers a webhook URL.

Auth: API key with full access (a key with scopes cannot call this route). Refused for every agent token (agent-token-credential).

Request body

JSON, the shape CreateWebhookRequest of the contract.

Field	Type	Required	Description
`url`	string	required	1 to 2048 characters.
`events`	array of `email.sent` \| `email.delivered` \| `email.delivery_delayed` \| `email.bounced` \| `email.complained` \| `email.failed` \| `email.received`	required	1 to any number of items.

Example request

curl -X POST "https://api.rytiv.app/v1/webhooks" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"<url>","events":["email.sent"]}'

Response

201 with a JSON object carrying secret and the fields of the object the handler builds.

Errors

Status	Code	Meaning
400	`bad-request`	The request is malformed or a field is out of range. `error` names every field; `issues` lists them.
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.

GET /v1/webhooks

The organization’s webhooks.

Auth: API key with full access or the scope read. Every class of agent token may call it.

Example request

curl -X GET "https://api.rytiv.app/v1/webhooks" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.

GET /v1/webhooks/:id

One webhook.

Auth: API key with full access or the scope read. Every class of agent token may call it.

Path parameters

Name	Description
`id`	The webhook’s id.

Example request

curl -X GET "https://api.rytiv.app/v1/webhooks/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.

GET /v1/webhooks/:id/deliveries

Its deliveries with their status.

Auth: API key with full access or the scope read. An agent token of class production needs prodDataRead for it; sandbox and twin may call it.

Path parameters

Name	Description
`id`	The object’s id.

Query parameters

Name	Description
`limit`	How many entries, at most.

Example request

curl -X GET "https://api.rytiv.app/v1/webhooks/<id>/deliveries" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a JSON body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.

DELETE /v1/webhooks/:id

Removes the webhook.

Auth: API key with full access (a key with scopes cannot call this route). Refused for every agent token (agent-token-credential).

Path parameters

Name	Description
`id`	The webhook’s id.

Example request

curl -X DELETE "https://api.rytiv.app/v1/webhooks/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

204 with no body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.