Webhooks

10 operations in the webhooks namespace.

webhooks.createEndpoint

POST /rpc/v1/webhooks.createEndpoint

Returns the signing secret ONCE. It is stored encrypted and is never readable again — an integrator who loses it rotates rather than retrieves. Verify a delivery by computing HMAC-SHA256(secret, "\{Roastery-Timestamp\}.\{raw body\}") and comparing it against any of the values in Roastery-Signature.

Requires permission webhooks.write and the api module on the organization’s plan.

Request

Field	Type	Required
`url`	string	yes
`description`	string	no
`eventTypes`	string[]	no

Example

curl -X POST https://api.roastery.run/rpc/v1/webhooks.createEndpoint \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

webhooks.deleteEndpoint

Remove a webhook endpoint

POST /rpc/v1/webhooks.deleteEndpoint

Requires permission webhooks.write and the api module on the organization’s plan.

Request

Field	Type	Required	Description
`id`	string	yes

Example

curl -X POST https://api.roastery.run/rpc/v1/webhooks.deleteEndpoint \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

webhooks.getEndpoint

Get one webhook endpoint

POST /rpc/v1/webhooks.getEndpoint

Also available as GET with a URL-encoded input query parameter, so the response can be HTTP-cached.

Requires permission webhooks.read and the api module on the organization’s plan.

Request

Field	Type	Required	Description
`id`	string	yes

Example

curl -X POST https://api.roastery.run/rpc/v1/webhooks.getEndpoint \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

webhooks.listDeliveries

Delivery attempts and their outcomes

POST /rpc/v1/webhooks.listDeliveries

Also available as GET with a URL-encoded input query parameter, so the response can be HTTP-cached.

The screen somebody debugging a broken integration is already looking at: what was sent, what came back, and when the next attempt is due.

Requires permission webhooks.read and the api module on the organization’s plan.

Request

Field	Type	Required	Description
`filter`	object	no
`page`	object	no

Example

curl -X POST https://api.roastery.run/rpc/v1/webhooks.listDeliveries \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

webhooks.listEndpoints

List webhook endpoints

POST /rpc/v1/webhooks.listEndpoints

Also available as GET with a URL-encoded input query parameter, so the response can be HTTP-cached.

Requires permission webhooks.read and the api module on the organization’s plan.

Request

Field	Type	Required	Description
`filter`	object	no
`page`	object	no

Example

curl -X POST https://api.roastery.run/rpc/v1/webhooks.listEndpoints \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

webhooks.listEvents

The raw event feed

POST /rpc/v1/webhooks.listEvents

Also available as GET with a URL-encoded input query parameter, so the response can be HTTP-cached.

Everything the organization has emitted, whether or not an endpoint was subscribed. This is the polling fallback for an integrator who cannot expose a public URL — and the reason a firewalled ERP is not shut out of the platform.

Requires permission webhooks.read and the api module on the organization’s plan.

Request

Field	Type	Required	Description
`filter`	object	no
`limit`	integer	no

Example

curl -X POST https://api.roastery.run/rpc/v1/webhooks.listEvents \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

webhooks.listEventTypes

Every event type this API publishes

POST /rpc/v1/webhooks.listEventTypes

Also available as GET with a URL-encoded input query parameter, so the response can be HTTP-cached.

The integration contract. An endpoint may subscribe to any of these exactly, to a prefix wildcard such as inventory.*, or to nothing at all — which subscribes it to everything, including types added later.

Requires permission webhooks.read and the api module on the organization’s plan.

Example

curl -X POST https://api.roastery.run/rpc/v1/webhooks.listEventTypes \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

webhooks.redeliver

Send a delivery again

POST /rpc/v1/webhooks.redeliver

Resets the attempt schedule and re-queues. The receiver sees the same event id, so a receiver that deduplicates on it — which the docs ask for — treats a redelivery of something it already handled as a no-op.

Requires permission webhooks.write and the api module on the organization’s plan.

Request

Field	Type	Required	Description
`id`	string	yes

Example

curl -X POST https://api.roastery.run/rpc/v1/webhooks.redeliver \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

webhooks.rotateSecret

Issue a new signing secret

POST /rpc/v1/webhooks.rotateSecret

During the overlap window every delivery carries TWO signatures and either verifies, so the new secret can be deployed whenever the integrator gets to it rather than at the same instant we start using it. Set overlapMinutes to 0 to cut over immediately, which is what you want after a leak.

Requires permission webhooks.write and the api module on the organization’s plan.

Request

Field	Type	Required	Description
`id`	string	yes
`overlapMinutes`	integer	no

Example

curl -X POST https://api.roastery.run/rpc/v1/webhooks.rotateSecret \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

webhooks.updateEndpoint

Change an endpoint’s subscription or status

POST /rpc/v1/webhooks.updateEndpoint

Setting status to active also clears the consecutive-failure count, which is how an auto-disabled endpoint is brought back once its server is fixed.

Requires permission webhooks.write and the api module on the organization’s plan.

Request

Field	Type	Required
`id`	string	yes
`description`	string,null	no
`eventTypes`	string[]	no
`status`	`active` \| `disabled`	no

Example

curl -X POST https://api.roastery.run/rpc/v1/webhooks.updateEndpoint \
  -H "Authorization: Bearer $ROASTERY_API_KEY" \
  -H "X-Roastery-Org: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{}'