03API reference

Version 1.0.0Made from openapi.yaml

Webhooks

Rollmark calls your server when something happens: an order is made, matched, cancelled, marked ready, shipped or delivered, or a distributor order changes status. Register an endpoint here; the events themselves are described under webhooks in this document. Every delivery is signed; see the guide on signatures.

GET/webhooksList webhook endpoints POST/webhooksRegister a webhook endpoint GET/webhooks/{id}One webhook endpoint PATCH/webhooks/{id}Change a webhook endpoint DELETE/webhooks/{id}Remove a webhook endpoint POST/webhooks/{id}/testSend a test event POST/webhooks/{id}/rotate-secretRotate the signing secret GET/webhooks/{id}/deliveriesThe delivery log POST/webhooks/{id}/deliveries/{delivery_id}/resendSend a delivery again

List webhook endpoints

GET/webhooks

Scoped private key (rm_prv_), from a server

webhooks:manage

Every endpoint of the store, without secrets. Needs the webhooks:manage permission.

Responses

200The endpoints.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object[]`
data[].`id`required	`string`
data[].`url`required	`string (uri)`	https only, port 443, a public host. Checked when it is registered and again at every delivery.
data[].`events`required	`("order.created" \| "order.matched" \| "order.cancelled" \| "order.ready" \| "order.shipped" \| "order.delivered" \| "distributor_order.status_changed")[]`
data[].`description`	`string`	Up to 200 characters.
data[].`state`required	`"enabled" \| "disabled" \| "disabled_failing" \| "disabled_key"`	`disabled_failing`: switched off after 20 failed deliveries in a row. `disabled_key`: the API key that made it was revoked.
data[].`disabled_reason`	`string \| null`
data[].`consecutive_failures`	`integer`
data[].`last_success_at`	`string (date-time) \| null`
data[].`last_failure_at`	`string (date-time) \| null`
data[].`created_at`required	`string (date-time)`

Errors401403429503in the error envelope.

Example

Shell
curl "https://app.getrollmark.com/api/v1/webhooks" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

Register a webhook endpoint

POST/webhooks

Scoped private key (rm_prv_), from a server

webhooks:manage

{ url, events, description? }. A store has at most 10 endpoints. The URL is checked now (https, port 443, a name that resolves only to public addresses) and at every delivery. You can subscribe only to events your key could read: order.* needs orders:read, distributor_order.* needs distributor_orders:read. The signing secret is in this answer and nowhere else. Needs the webhooks:manage permission.

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	`string`	1 to 255 printable characters (a UUID is fine). The first request with a key runs and its answer is kept for 24 hours; the same request again gets the same answer with `Idempotent-Replay: true`. The same key with a different method, path or body is `409 idempotency_conflict`. A refusal is not kept, so a corrected request can use the same key. 1 to 255 characters.

Request body

Field	Type	Description
`url`required	`string`
`events`required	`("order.created" \| "order.matched" \| "order.cancelled" \| "order.ready" \| "order.shipped" \| "order.delivered" \| "distributor_order.status_changed")[]`	At least 1 item.
`description`	`string`	Up to 200 characters.

Responses

201Registered.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`
data.`url`required	`string (uri)`	https only, port 443, a public host. Checked when it is registered and again at every delivery.
data.`events`required	`("order.created" \| "order.matched" \| "order.cancelled" \| "order.ready" \| "order.shipped" \| "order.delivered" \| "distributor_order.status_changed")[]`
data.`description`	`string`	Up to 200 characters.
data.`state`required	`"enabled" \| "disabled" \| "disabled_failing" \| "disabled_key"`	`disabled_failing`: switched off after 20 failed deliveries in a row. `disabled_key`: the API key that made it was revoked.
data.`disabled_reason`	`string \| null`
data.`consecutive_failures`	`integer`
data.`last_success_at`	`string (date-time) \| null`
data.`last_failure_at`	`string (date-time) \| null`
data.`created_at`required	`string (date-time)`
data.`secret`required	`string`	The signing secret (`whsec_...`). Shown here once and never again; store it now. If it is lost, rotate it.

Errors400401403429503in the error envelope.

Example

Shell
curl -X POST "https://app.getrollmark.com/api/v1/webhooks" \
  -H "Authorization: Bearer $ROLLMARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"…","events":["order.created"]}'

One webhook endpoint

GET/webhooks/{id}

Scoped private key (rm_prv_), from a server

webhooks:manage

Needs the webhooks:manage permission.

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200The endpoint.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`
data.`url`required	`string (uri)`	https only, port 443, a public host. Checked when it is registered and again at every delivery.
data.`events`required	`("order.created" \| "order.matched" \| "order.cancelled" \| "order.ready" \| "order.shipped" \| "order.delivered" \| "distributor_order.status_changed")[]`
data.`description`	`string`	Up to 200 characters.
data.`state`required	`"enabled" \| "disabled" \| "disabled_failing" \| "disabled_key"`	`disabled_failing`: switched off after 20 failed deliveries in a row. `disabled_key`: the API key that made it was revoked.
data.`disabled_reason`	`string \| null`
data.`consecutive_failures`	`integer`
data.`last_success_at`	`string (date-time) \| null`
data.`last_failure_at`	`string (date-time) \| null`
data.`created_at`required	`string (date-time)`

Errors401403404429503in the error envelope.

Example

Shell
curl "https://app.getrollmark.com/api/v1/webhooks/<id>" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

Change a webhook endpoint

PATCH/webhooks/{id}

Scoped private key (rm_prv_), from a server

webhooks:manage

{ url?, events?, description?, state? }. state is enabled or disabled; enabling an endpoint that was switched off for failing clears its failure count. An endpoint switched off because its key was revoked cannot be enabled (409): make a new one. Needs the webhooks:manage permission.

Parameters

Name	In	Type	Description
`id`required	path	`string`
`Idempotency-Key`	header	`string`	1 to 255 printable characters (a UUID is fine). The first request with a key runs and its answer is kept for 24 hours; the same request again gets the same answer with `Idempotent-Replay: true`. The same key with a different method, path or body is `409 idempotency_conflict`. A refusal is not kept, so a corrected request can use the same key. 1 to 255 characters.

Request body

Field	Type	Description
`url`	`string`
`events`	`("order.created" \| "order.matched" \| "order.cancelled" \| "order.ready" \| "order.shipped" \| "order.delivered" \| "distributor_order.status_changed")[]`	At least 1 item.
`description`	`string`	Up to 200 characters.
`state`	`"enabled" \| "disabled"`

Responses

200The endpoint.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`
data.`url`required	`string (uri)`	https only, port 443, a public host. Checked when it is registered and again at every delivery.
data.`events`required	`("order.created" \| "order.matched" \| "order.cancelled" \| "order.ready" \| "order.shipped" \| "order.delivered" \| "distributor_order.status_changed")[]`
data.`description`	`string`	Up to 200 characters.
data.`state`required	`"enabled" \| "disabled" \| "disabled_failing" \| "disabled_key"`	`disabled_failing`: switched off after 20 failed deliveries in a row. `disabled_key`: the API key that made it was revoked.
data.`disabled_reason`	`string \| null`
data.`consecutive_failures`	`integer`
data.`last_success_at`	`string (date-time) \| null`
data.`last_failure_at`	`string (date-time) \| null`
data.`created_at`required	`string (date-time)`

Errors400401403404409429503in the error envelope.

Example

Shell
curl -X PATCH "https://app.getrollmark.com/api/v1/webhooks/<id>" \
  -H "Authorization: Bearer $ROLLMARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Remove a webhook endpoint

DELETE/webhooks/{id}

Scoped private key (rm_prv_), from a server

webhooks:manage

With its log. Needs the webhooks:manage permission.

Parameters

Name	In	Type	Description
`id`required	path	`string`
`Idempotency-Key`	header	`string`	1 to 255 printable characters (a UUID is fine). The first request with a key runs and its answer is kept for 24 hours; the same request again gets the same answer with `Idempotent-Replay: true`. The same key with a different method, path or body is `409 idempotency_conflict`. A refusal is not kept, so a corrected request can use the same key. 1 to 255 characters.

Responses

200Removed.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`
data.`deleted`required	`true`

Errors401403404429503in the error envelope.

Example

Shell
curl -X DELETE "https://app.getrollmark.com/api/v1/webhooks/<id>" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

Send a test event

POST/webhooks/{id}/test

Scoped private key (rm_prv_), from a server

webhooks:manage

Queues a ping event; Rollmark delivers it within a few seconds. See the result in the deliveries. The endpoint must be enabled (409 otherwise). Needs the webhooks:manage permission.

Parameters

Name	In	Type	Description
`id`required	path	`string`
`Idempotency-Key`	header	`string`	1 to 255 printable characters (a UUID is fine). The first request with a key runs and its answer is kept for 24 hours; the same request again gets the same answer with `Idempotent-Replay: true`. The same key with a different method, path or body is `409 idempotency_conflict`. A refusal is not kept, so a corrected request can use the same key. 1 to 255 characters.

Responses

202Queued.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`
data.`endpoint_id`required	`string`
data.`event_id`required	`string`	The event's id (`evt_...`), the same on every retry and resend.
data.`event_type`required	`string`
data.`state`required	`"pending" \| "retrying" \| "delivered" \| "dead"`
data.`attempts`required	`integer`
data.`last_status`	`integer \| null`
data.`last_error`	`string \| null`	A short reason; never the receiver's reply.
data.`created_at`required	`string (date-time)`
data.`delivered_at`	`string (date-time) \| null`
data.`next_attempt_at`	`string (date-time) \| null`
data.`resent_from`	`string \| null`

Errors401403404409429503in the error envelope.

Example

Shell
curl -X POST "https://app.getrollmark.com/api/v1/webhooks/<id>/test" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

Rotate the signing secret

POST/webhooks/{id}/rotate-secret

Scoped private key (rm_prv_), from a server

webhooks:manage

A new secret, shown once. For 24 hours each delivery is signed with both (Rollmark-Signature: v1=<new>,v1=<old>), so a receiver can switch without a gap. Needs the webhooks:manage permission.

Parameters

Name	In	Type	Description
`id`required	path	`string`
`Idempotency-Key`	header	`string`	1 to 255 printable characters (a UUID is fine). The first request with a key runs and its answer is kept for 24 hours; the same request again gets the same answer with `Idempotent-Replay: true`. The same key with a different method, path or body is `409 idempotency_conflict`. A refusal is not kept, so a corrected request can use the same key. 1 to 255 characters.

Responses

200The new secret.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`
data.`secret`required	`string`	The new signing secret

Errors401403404429503in the error envelope.

Example

Shell
curl -X POST "https://app.getrollmark.com/api/v1/webhooks/<id>/rotate-secret" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

The delivery log

GET/webhooks/{id}/deliveries

Scoped private key (rm_prv_), from a server

webhooks:manage

Newest first, with a cursor. Ids, states and short reasons only: the payload is not shown. A delivery is delivered (a 2xx), retrying (failed, due again), or dead (failed 8 times over about two days, or waited more than 72 hours). Needs the webhooks:manage permission.

Parameters

Name	In	Type	Description
`id`required	path	`string`
`limit`	query	`integer`	Default 50. 1 to 100.
`cursor`	query	`string`	The `next_cursor` of the previous page. Opaque; do not build or change one. A cursor belongs to the request that produced it; with other parameters it is `bad_cursor`. Up to 2048 characters.

Responses

200A page.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object[]`
data[].`id`required	`string`
data[].`endpoint_id`required	`string`
data[].`event_id`required	`string`	The event's id (`evt_...`), the same on every retry and resend.
data[].`event_type`required	`string`
data[].`state`required	`"pending" \| "retrying" \| "delivered" \| "dead"`
data[].`attempts`required	`integer`
data[].`last_status`	`integer \| null`
data[].`last_error`	`string \| null`	A short reason; never the receiver's reply.
data[].`created_at`required	`string (date-time)`
data[].`delivered_at`	`string (date-time) \| null`
data[].`next_attempt_at`	`string (date-time) \| null`
data[].`resent_from`	`string \| null`
`next_cursor`required	`string \| null`

Errors400401403404429503in the error envelope.

Example

Shell
curl "https://app.getrollmark.com/api/v1/webhooks/<id>/deliveries" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

Send a delivery again

POST/webhooks/{id}/deliveries/{delivery_id}/resend

Scoped private key (rm_prv_), from a server

webhooks:manage

Sends the same event (the same id, so a receiver that has it can drop it) as a new delivery. The endpoint must be enabled (409 otherwise). Needs the webhooks:manage permission.

Parameters

Name	In	Type	Description
`id`required	path	`string`
`delivery_id`required	path	`string`
`Idempotency-Key`	header	`string`	1 to 255 printable characters (a UUID is fine). The first request with a key runs and its answer is kept for 24 hours; the same request again gets the same answer with `Idempotent-Replay: true`. The same key with a different method, path or body is `409 idempotency_conflict`. A refusal is not kept, so a corrected request can use the same key. 1 to 255 characters.

Responses

202Queued.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`
data.`endpoint_id`required	`string`
data.`event_id`required	`string`	The event's id (`evt_...`), the same on every retry and resend.
data.`event_type`required	`string`
data.`state`required	`"pending" \| "retrying" \| "delivered" \| "dead"`
data.`attempts`required	`integer`
data.`last_status`	`integer \| null`
data.`last_error`	`string \| null`	A short reason; never the receiver's reply.
data.`created_at`required	`string (date-time)`
data.`delivered_at`	`string (date-time) \| null`
data.`next_attempt_at`	`string (date-time) \| null`
data.`resent_from`	`string \| null`

Errors401403404409429503in the error envelope.

Example

Shell
curl -X POST "https://app.getrollmark.com/api/v1/webhooks/<id>/deliveries/<delivery_id>/resend" \
  -H "Authorization: Bearer $ROLLMARK_KEY"