Webhooks

GET /v1/webhook-endpoints

List webhook endpoints

webhooks:manage

Request exampleNo request body

curl

curl https://api.rieckflow.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $RIECK_API_KEY"

TypeScript

const svar = await rieck.request("GET", "/v1/webhook-endpoints");

Response

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "url": "https://erp.acme.example/webhooks/rieck",
    "description": "Production events",
    "eventTypes": [
      "invoice.paid",
      "customer.past_due"
    ],
    "active": true,
    "previousSecretExpiresAt": null,
    "createdAt": "2026-08-04T09:32:11Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
data.id	uuid	Stable endpoint id.
data.url	url	HTTPS delivery destination.
data.eventTypes	string[]	Subscribed event types.
data.active	boolean	Whether delivery is enabled.
data.secret	string	Only returned when creating or rotating the endpoint.

Possible errors 4

HTTP	Code	Meaning
401	invalid_api_key	The API key is missing, invalid, expired or revoked.
403	api_not_included	The organisation’s plan does not include API access.
403	insufficient_scope	The key does not have the required scope.
429	rate_limited	The organisation’s rate budget is exhausted.

---

POST /v1/webhook-endpoints

Register endpoint

webhooks:manage

Response carries the signing secret exactly once. HTTPS only; private hosts rejected; max 10 per organisation (a hard limit in the database, not a soft one — every event costs one queue row PER endpoint). Choose payloadStyle: snapshot (default) sends the whitelisted fields as they were when the event was queued; thin sends the SAME envelope with an empty data and you fetch the object fresh. Prefer thin: less of your customers’ data leaves our systems, and you act on current state rather than on a snapshot that may be half an hour old by the time delivery succeeds.

Request body fields 4

Field	Type	Required	Description
url	string	Yes	Public HTTPS endpoint that receives signed events.
eventTypes	string[]	Yes	Event types delivered to the endpoint.
description	string	No	Human-readable description.
payloadStyle	string	No	Field in the request payload.

Request exampleapplication/json

curl

curl -X POST https://api.rieckflow.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.acme.example/webhooks/rieck",
    "eventTypes": [
      "…"
    ],
    "description": "Consulting",
    "payloadStyle": "snapshot"
  }'

TypeScript

const svar = await rieck.request("POST", "/v1/webhook-endpoints", {
  body: {
    "url": "https://erp.acme.example/webhooks/rieck",
    "eventTypes": [
      "…"
    ],
    "description": "Consulting",
    "payloadStyle": "snapshot"
  },
});

Response

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "url": "https://erp.acme.example/webhooks/rieck",
    "description": "Production events",
    "eventTypes": [
      "invoice.paid",
      "customer.past_due"
    ],
    "active": true,
    "previousSecretExpiresAt": null,
    "createdAt": "2026-08-04T09:32:11Z",
    "secret": "whsec_7a4db0f80d2c4c74"
  }
}

201 Success envelopeapplication/json

Response fields 5

Field	Type	Description
data.id	uuid	Stable endpoint id.
data.url	url	HTTPS delivery destination.
data.eventTypes	string[]	Subscribed event types.
data.active	boolean	Whether delivery is enabled.
data.secret	string	Only returned when creating or rotating the endpoint.

Possible errors 9

HTTP	Code	Meaning
400	invalid_idempotency_key	Idempotency-Key is missing or malformed.
400	invalid_request	The request body or parameter failed validation.
401	invalid_api_key	The API key is missing, invalid, expired or revoked.
403	api_not_included	The organisation’s plan does not include API access.
403	insufficient_scope	The key does not have the required scope.
409	idempotency_conflict	The same key was used with a different request.
409	idempotency_in_progress	The same operation is currently being processed. Retry later.
413	payload_too_large	The JSON or uploaded file exceeds this endpoint’s size limit.
429	rate_limited	The organisation’s rate budget is exhausted.

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "eventTypes": {
      "minItems": 1,
      "maxItems": 75,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "payloadStyle": {
      "default": "snapshot",
      "type": "string",
      "enum": [
        "snapshot",
        "thin"
      ]
    }
  },
  "required": [
    "url",
    "eventTypes"
  ],
  "additionalProperties": false
}

---

GET /v1/webhook-endpoints/{endpointId}

Get endpoint

webhooks:manage

Parameter	In	Type	Required	Description
endpointId	path	string	Yes

Request exampleNo request body

curl

curl https://api.rieckflow.com/v1/webhook-endpoints/9b2f1c1e-… \
  -H "Authorization: Bearer $RIECK_API_KEY"

TypeScript

const svar = await rieck.request("GET", "/v1/webhook-endpoints/9b2f1c1e-…");

Response

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "url": "https://erp.acme.example/webhooks/rieck",
    "description": "Production events",
    "eventTypes": [
      "invoice.paid",
      "customer.past_due"
    ],
    "active": true,
    "previousSecretExpiresAt": null,
    "createdAt": "2026-08-04T09:32:11Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
data.id	uuid	Stable endpoint id.
data.url	url	HTTPS delivery destination.
data.eventTypes	string[]	Subscribed event types.
data.active	boolean	Whether delivery is enabled.
data.secret	string	Only returned when creating or rotating the endpoint.

Possible errors 5

HTTP	Code	Meaning
401	invalid_api_key	The API key is missing, invalid, expired or revoked.
403	api_not_included	The organisation’s plan does not include API access.
403	insufficient_scope	The key does not have the required scope.
404	webhook_endpoint_not_found	The webhook endpoint does not exist or is inactive.
429	rate_limited	The organisation’s rate budget is exhausted.

---

PATCH /v1/webhook-endpoints/{endpointId}

Update endpoint

webhooks:manage

The URL cannot be changed — register a new endpoint instead. Omitting payloadStyle leaves it unchanged; it is never reset to the default, because that would start sending event data to an endpoint that deliberately opted out. A change takes effect on the NEXT delivery attempt, including for events already queued.

Parameter	In	Type	Required	Description
endpointId	path	string	Yes

Request body fields 4

Field	Type	Required	Description
eventTypes	string[]	No	Event types delivered to the endpoint.
active	boolean	No	Whether the resource is active.
description	string	No	Human-readable description.
payloadStyle	string	No	Field in the request payload.

Request exampleapplication/json

curl

curl -X PATCH https://api.rieckflow.com/v1/webhook-endpoints/9b2f1c1e-… \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypes": [
      "…"
    ],
    "active": true,
    "description": "Consulting",
    "payloadStyle": "snapshot"
  }'

TypeScript

const svar = await rieck.request("PATCH", "/v1/webhook-endpoints/9b2f1c1e-…", {
  body: {
    "eventTypes": [
      "…"
    ],
    "active": true,
    "description": "Consulting",
    "payloadStyle": "snapshot"
  },
});

Response

{
  "data": {
    "id": "9b2f1c1e-6b87-4d9b-91a0-47c8d72b8440",
    "url": "https://erp.acme.example/webhooks/rieck",
    "description": "Production events",
    "eventTypes": [
      "invoice.paid",
      "customer.past_due"
    ],
    "active": true,
    "previousSecretExpiresAt": null,
    "createdAt": "2026-08-04T09:32:11Z"
  }
}

200 Success envelopeapplication/json

Response fields 5

Field	Type	Description
data.id	uuid	Stable endpoint id.
data.url	url	HTTPS delivery destination.
data.eventTypes	string[]	Subscribed event types.
data.active	boolean	Whether delivery is enabled.
data.secret	string	Only returned when creating or rotating the endpoint.

Possible errors 10

HTTP	Code	Meaning
400	invalid_idempotency_key	Idempotency-Key is missing or malformed.
400	invalid_request	The request body or parameter failed validation.
401	invalid_api_key	The API key is missing, invalid, expired or revoked.
403	api_not_included	The organisation’s plan does not include API access.
403	insufficient_scope	The key does not have the required scope.
404	webhook_endpoint_not_found	The webhook endpoint does not exist or is inactive.
409	idempotency_conflict	The same key was used with a different request.
409	idempotency_in_progress	The same operation is currently being processed. Retry later.
413	payload_too_large	The JSON or uploaded file exceeds this endpoint’s size limit.
429	rate_limited	The organisation’s rate budget is exhausted.

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "eventTypes": {
      "minItems": 1,
      "maxItems": 75,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "active": {
      "type": "boolean"
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200
        },
        {
          "type": "null"
        }
      ]
    },
    "payloadStyle": {
      "type": "string",
      "enum": [
        "snapshot",
        "thin"
      ]
    }
  },
  "additionalProperties": false
}

---

DELETE /v1/webhook-endpoints/{endpointId}

Delete endpoint

webhooks:manage

Parameter	In	Type	Required	Description
endpointId	path	string	Yes

Request exampleNo request body

curl

curl -X DELETE https://api.rieckflow.com/v1/webhook-endpoints/9b2f1c1e-… \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041"

TypeScript

const svar = await rieck.request("DELETE", "/v1/webhook-endpoints/9b2f1c1e-…");

204 No contentNo response body

Possible errors 8

HTTP	Code	Meaning
400	invalid_idempotency_key	Idempotency-Key is missing or malformed.
401	invalid_api_key	The API key is missing, invalid, expired or revoked.
403	api_not_included	The organisation’s plan does not include API access.
403	insufficient_scope	The key does not have the required scope.
404	webhook_endpoint_not_found	The webhook endpoint does not exist or is inactive.
409	idempotency_conflict	The same key was used with a different request.
409	idempotency_in_progress	The same operation is currently being processed. Retry later.
429	rate_limited	The organisation’s rate budget is exhausted.

---

POST /v1/webhook-endpoints/{endpointId}/rotate-secret

Rotate secret (24 h overlap)

webhooks:manage

Parameter	In	Type	Required	Description
endpointId	path	string	Yes

Request exampleNo request body

curl

curl -X POST https://api.rieckflow.com/v1/webhook-endpoints/9b2f1c1e-…/rotate-secret \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041"

TypeScript

const svar = await rieck.request("POST", "/v1/webhook-endpoints/9b2f1c1e-…/rotate-secret");

Response

{
  "data": {
    "secret": "whsec_7a4db0f80d2c4c74",
    "previousSecretValidFor": "24h"
  }
}

200 Success envelopeapplication/json

Possible errors 8

HTTP	Code	Meaning
400	invalid_idempotency_key	Idempotency-Key is missing or malformed.
401	invalid_api_key	The API key is missing, invalid, expired or revoked.
403	api_not_included	The organisation’s plan does not include API access.
403	insufficient_scope	The key does not have the required scope.
404	webhook_endpoint_not_found	The webhook endpoint does not exist or is inactive.
409	idempotency_conflict	The same key was used with a different request.
409	idempotency_in_progress	The same operation is currently being processed. Retry later.
429	rate_limited	The organisation’s rate budget is exhausted.

---

POST /v1/webhook-endpoints/{endpointId}/test

Send test ping

webhooks:manage

Parameter	In	Type	Required	Description
endpointId	path	string	Yes

Request exampleNo request body

curl

curl -X POST https://api.rieckflow.com/v1/webhook-endpoints/9b2f1c1e-…/test \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041"

TypeScript

const svar = await rieck.request("POST", "/v1/webhook-endpoints/9b2f1c1e-…/test");

Response

{
  "data": {
    "queued": true
  }
}

202 Success envelopeapplication/json

Possible errors 8

HTTP	Code	Meaning
400	invalid_idempotency_key	Idempotency-Key is missing or malformed.
401	invalid_api_key	The API key is missing, invalid, expired or revoked.
403	api_not_included	The organisation’s plan does not include API access.
403	insufficient_scope	The key does not have the required scope.
404	webhook_endpoint_not_found	The webhook endpoint does not exist or is inactive.
409	idempotency_conflict	The same key was used with a different request.
409	idempotency_in_progress	The same operation is currently being processed. Retry later.
429	rate_limited	The organisation’s rate budget is exhausted.

---

POST /v1/webhook-endpoints/{endpointId}/replay

Replay deliveries

webhooks:manage

Re-queues failed/given-up deliveries and enqueues never-queued events since since. RETENTION CONTRACT: events are kept and replayable for 90 days; since older than that is rejected (422), and so is a since in the future. At most 10,000 never-queued events are enqueued per call — call again with a later since to continue. Delivered events are never re-sent, so a replay is safe to repeat.

Parameter	In	Type	Required	Description
endpointId	path	string	Yes

Request body fields 1

Field	Type	Required	Description
since	string	Yes	Field in the request payload.

Request exampleapplication/json

curl

curl -X POST https://api.rieckflow.com/v1/webhook-endpoints/9b2f1c1e-…/replay \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -d '{
    "since": "2026-08-15"
  }'

TypeScript

const svar = await rieck.request("POST", "/v1/webhook-endpoints/9b2f1c1e-…/replay", {
  body: {
    "since": "2026-08-15"
  },
});

Response

{
  "data": {
    "requeued": 3,
    "enqueued": 12,
    "possiblyMore": false
  }
}

200 Success envelopeapplication/json

Possible errors 11

HTTP	Code	Meaning
400	invalid_idempotency_key	Idempotency-Key is missing or malformed.
400	invalid_request	The request body or parameter failed validation.
401	invalid_api_key	The API key is missing, invalid, expired or revoked.
403	api_not_included	The organisation’s plan does not include API access.
403	insufficient_scope	The key does not have the required scope.
404	webhook_endpoint_not_found	The webhook endpoint does not exist or is inactive.
409	idempotency_conflict	The same key was used with a different request.
409	idempotency_in_progress	The same operation is currently being processed. Retry later.
413	payload_too_large	The JSON or uploaded file exceeds this endpoint’s size limit.
422	replay_window_exceeded	Webhook replay is limited to the last 90 days.
429	rate_limited	The organisation’s rate budget is exhausted.

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "since": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        }
      ]
    }
  },
  "required": [
    "since"
  ],
  "additionalProperties": false
}