API reference

Webhooks

8 operations. Base URL: https://api.ringura.com/api/v1. Authenticate with a bearer token that carries the scope named on each operation.

GET `/api/v1/event-types`

The event catalogue an endpoint can subscribe to.

Scope: webhooks:read
Operation id: listEventTypes

Response

200 JSON with these fields.

Response fields of GET /api/v1/event-types
Field	Type	Required
`data`	array of object	Yes
`data[].type`	string	Yes
`data[].summary`	string	Yes
`data[].data`	array of string	Yes

Errors

400, 401, 403, 404, 409, 429. What each status means

Example request

curl -X GET 'https://api.ringura.com/api/v1/event-types' \
  -H "Authorization: Bearer $CC_TOKEN"

GET `/api/v1/webhook-endpoints`

The tenant's webhook endpoints.

Scope: webhooks:read
Operation id: listWebhookEndpoints

Parameters

Parameters of GET /api/v1/webhook-endpoints
Name	In	Type	Required	Constraints
`limit`	query	integer	No	1 to 200
`cursor`	query	string	No	at most 400 characters

Response

200 JSON with these fields.

Response fields of GET /api/v1/webhook-endpoints
Field	Type	Required	Constraints
`data`	array of object	Yes
`data[].id`	string (uuid)	Yes
`data[].url`	string	Yes
`data[].description`	string or null	Yes
`data[].eventTypes`	array of string	Yes
`data[].status`	string	Yes	one of "active", "disabled"
`data[].rotating`	boolean	Yes
`data[].previousSecretExpiresAt`	string (date-time) or null	Yes
`data[].createdAt`	string (date-time)	Yes
`data[].updatedAt`	string (date-time)	Yes
`nextCursor`	string or null	Yes

Errors

400, 401, 403, 404, 409, 429. What each status means

Example request

curl -X GET 'https://api.ringura.com/api/v1/webhook-endpoints' \
  -H "Authorization: Bearer $CC_TOKEN"

POST `/api/v1/webhook-endpoints`

Subscribe a URL to event types. The signing secret is in this answer only.

Scope: webhooks:write
Operation id: createWebhookEndpoint
Idempotent: Send Idempotency-Key to make a retry safe

Parameters

Parameters of POST /api/v1/webhook-endpoints
Name	In	Type	Required	Constraints
`Idempotency-Key`	header	string	No	matches ^[A-Za-z0-9_.:-]{8,100}$

Request body

JSON (Content-Type: application/json).

Request body of POST /api/v1/webhook-endpoints
Field	Type	Required	Constraints
`url`	string	Yes	at most 2000 characters
`eventTypes`	array of string	Yes	at least 1 items at most 100 items
`description`	string or null	No	at most 200 characters

Response

201 JSON with these fields.

Response fields of POST /api/v1/webhook-endpoints
Field	Type	Required	Constraints
`endpoint`	object	Yes
`endpoint.id`	string (uuid)	Yes
`endpoint.url`	string	Yes
`endpoint.description`	string or null	Yes
`endpoint.eventTypes`	array of string	Yes
`endpoint.status`	string	Yes	one of "active", "disabled"
`endpoint.rotating`	boolean	Yes
`endpoint.previousSecretExpiresAt`	string (date-time) or null	Yes
`endpoint.createdAt`	string (date-time)	Yes
`endpoint.updatedAt`	string (date-time)	Yes
`secret`	string	Yes

Errors

400, 401, 403, 404, 409, 422, 429. What each status means

Example request

curl -X POST 'https://api.ringura.com/api/v1/webhook-endpoints' \
  -H "Authorization: Bearer $CC_TOKEN" \
  -H 'Idempotency-Key: order-2027-0001' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://crm.example.com/hooks/cc",
  "eventTypes": [
    "example"
  ]
}'

GET `/api/v1/webhook-endpoints/{id}`

One endpoint.

Scope: webhooks:read
Operation id: getWebhookEndpoint

Parameters

Parameters of GET /api/v1/webhook-endpoints/{id}
Name	In	Type	Required	Constraints
`id`	path	string (uuid)	Yes

Response

200 JSON with these fields.

Response fields of GET /api/v1/webhook-endpoints/{id}
Field	Type	Required	Constraints
`id`	string (uuid)	Yes
`url`	string	Yes
`description`	string or null	Yes
`eventTypes`	array of string	Yes
`status`	string	Yes	one of "active", "disabled"
`rotating`	boolean	Yes
`previousSecretExpiresAt`	string (date-time) or null	Yes
`createdAt`	string (date-time)	Yes
`updatedAt`	string (date-time)	Yes

Errors

400, 401, 403, 404, 409, 429. What each status means

Example request

curl -X GET 'https://api.ringura.com/api/v1/webhook-endpoints/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e' \
  -H "Authorization: Bearer $CC_TOKEN"

PATCH `/api/v1/webhook-endpoints/{id}`

Change an endpoint's URL, event types or status.

Scope: webhooks:write
Operation id: updateWebhookEndpoint
Idempotent: Send Idempotency-Key to make a retry safe

Parameters

Parameters of PATCH /api/v1/webhook-endpoints/{id}
Name	In	Type	Required	Constraints
`id`	path	string (uuid)	Yes
`Idempotency-Key`	header	string	No	matches ^[A-Za-z0-9_.:-]{8,100}$

Request body

JSON (Content-Type: application/json).

Request body of PATCH /api/v1/webhook-endpoints/{id}
Field	Type	Required	Constraints
`url`	string	No	at most 2000 characters
`eventTypes`	array of string	No	at least 1 items at most 100 items
`description`	string or null	No	at most 200 characters
`status`	string	No	one of "active", "disabled"

Response

200 JSON with these fields.

Response fields of PATCH /api/v1/webhook-endpoints/{id}
Field	Type	Required	Constraints
`id`	string (uuid)	Yes
`url`	string	Yes
`description`	string or null	Yes
`eventTypes`	array of string	Yes
`status`	string	Yes	one of "active", "disabled"
`rotating`	boolean	Yes
`previousSecretExpiresAt`	string (date-time) or null	Yes
`createdAt`	string (date-time)	Yes
`updatedAt`	string (date-time)	Yes

Errors

400, 401, 403, 404, 409, 422, 429. What each status means

Example request

curl -X PATCH 'https://api.ringura.com/api/v1/webhook-endpoints/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e' \
  -H "Authorization: Bearer $CC_TOKEN" \
  -H 'Idempotency-Key: order-2027-0001' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://crm.example.com/hooks/cc"
}'

POST `/api/v1/webhook-endpoints/{id}/rotate-secret`

A new signing secret; for 24 hours deliveries are signed under both.

Scope: webhooks:write
Operation id: rotateWebhookSecret
Idempotent: Send Idempotency-Key to make a retry safe

Parameters

Parameters of POST /api/v1/webhook-endpoints/{id}/rotate-secret
Name	In	Type	Required	Constraints
`id`	path	string (uuid)	Yes
`Idempotency-Key`	header	string	No	matches ^[A-Za-z0-9_.:-]{8,100}$

Response

200 JSON with these fields.

Response fields of POST /api/v1/webhook-endpoints/{id}/rotate-secret
Field	Type	Required	Constraints
`endpoint`	object	Yes
`endpoint.id`	string (uuid)	Yes
`endpoint.url`	string	Yes
`endpoint.description`	string or null	Yes
`endpoint.eventTypes`	array of string	Yes
`endpoint.status`	string	Yes	one of "active", "disabled"
`endpoint.rotating`	boolean	Yes
`endpoint.previousSecretExpiresAt`	string (date-time) or null	Yes
`endpoint.createdAt`	string (date-time)	Yes
`endpoint.updatedAt`	string (date-time)	Yes
`secret`	string	Yes

Errors

400, 401, 403, 404, 409, 422, 429. What each status means

Example request

curl -X POST 'https://api.ringura.com/api/v1/webhook-endpoints/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e/rotate-secret' \
  -H "Authorization: Bearer $CC_TOKEN" \
  -H 'Idempotency-Key: order-2027-0001'

GET `/api/v1/webhook-deliveries`

Deliveries, newest first; dead ones are the dead letter.

Scope: webhooks:read
Operation id: listWebhookDeliveries

Parameters

Parameters of GET /api/v1/webhook-deliveries
Name	In	Type	Required	Constraints
`limit`	query	integer	No	1 to 200
`cursor`	query	string	No	at most 400 characters
`endpointId`	query	string (uuid)	No
`status`	query	string	No	one of "pending", "sending", "delivered", "dead"

Response

200 JSON with these fields.

Response fields of GET /api/v1/webhook-deliveries
Field	Type	Required	Constraints
`data`	array of object	Yes
`data[].id`	string (uuid)	Yes
`data[].endpointId`	string (uuid)	Yes
`data[].eventId`	string	Yes
`data[].eventType`	string	Yes
`data[].status`	string	Yes	one of "pending", "sending", "delivered", "dead"
`data[].attempts`	integer	Yes
`data[].nextAttemptAt`	string (date-time) or null	Yes
`data[].lastStatusCode`	integer or null	Yes
`data[].lastError`	string or null	Yes
`data[].deliveredAt`	string (date-time) or null	Yes
`data[].replayOf`	string (uuid) or null	Yes
`data[].createdAt`	string (date-time)	Yes
`nextCursor`	string or null	Yes

Errors

400, 401, 403, 404, 409, 429. What each status means

Example request

curl -X GET 'https://api.ringura.com/api/v1/webhook-deliveries' \
  -H "Authorization: Bearer $CC_TOKEN"

POST `/api/v1/webhook-deliveries/{id}/replay`

Send a delivered or dead event again, as a new delivery with the same event id.

Scope: webhooks:write
Operation id: replayWebhookDelivery
Idempotent: Send Idempotency-Key to make a retry safe

Parameters

Parameters of POST /api/v1/webhook-deliveries/{id}/replay
Name	In	Type	Required	Constraints
`id`	path	string (uuid)	Yes
`Idempotency-Key`	header	string	No	matches ^[A-Za-z0-9_.:-]{8,100}$

Response

201 JSON with these fields.

Response fields of POST /api/v1/webhook-deliveries/{id}/replay
Field	Type	Required	Constraints
`id`	string (uuid)	Yes
`endpointId`	string (uuid)	Yes
`eventId`	string	Yes
`eventType`	string	Yes
`status`	string	Yes	one of "pending", "sending", "delivered", "dead"
`attempts`	integer	Yes
`nextAttemptAt`	string (date-time) or null	Yes
`lastStatusCode`	integer or null	Yes
`lastError`	string or null	Yes
`deliveredAt`	string (date-time) or null	Yes
`replayOf`	string (uuid) or null	Yes
`createdAt`	string (date-time)	Yes

Errors

400, 401, 403, 404, 409, 422, 429. What each status means

Example request

curl -X POST 'https://api.ringura.com/api/v1/webhook-deliveries/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e/replay' \
  -H "Authorization: Bearer $CC_TOKEN" \
  -H 'Idempotency-Key: order-2027-0001'

Webhooks

GET /api/v1/event-types

Response

Errors

Example request

GET /api/v1/webhook-endpoints

Parameters

Response

Errors

Example request

POST /api/v1/webhook-endpoints

Parameters

Request body

Response

Errors

Example request

GET /api/v1/webhook-endpoints/{id}

Parameters

Response

Errors

Example request

PATCH /api/v1/webhook-endpoints/{id}

Parameters

Request body

Response

Errors

Example request

POST /api/v1/webhook-endpoints/{id}/rotate-secret

Parameters

Response

Errors

Example request

GET /api/v1/webhook-deliveries

Parameters

Response

Errors

Example request

POST /api/v1/webhook-deliveries/{id}/replay

Parameters

Response

Errors

Example request

GET `/api/v1/event-types`

GET `/api/v1/webhook-endpoints`

POST `/api/v1/webhook-endpoints`

GET `/api/v1/webhook-endpoints/{id}`

PATCH `/api/v1/webhook-endpoints/{id}`

POST `/api/v1/webhook-endpoints/{id}/rotate-secret`

GET `/api/v1/webhook-deliveries`

POST `/api/v1/webhook-deliveries/{id}/replay`