webhooks

Webhooks

Cintra can notify your system when something happens, by sending an HTTPS POST to an endpoint you provide. Endpoints and the event types they receive are set up by Cintra on request; there is no API to manage them.

Only the event types listed below can be subscribed to. They are a stable contract: once published, a type's name and record fields do not change. A different shape is published as a new event type.

---

Event types

Event type	When it is sent	Record fields
PaymentRunCreatedExternal	A payment run has been created	paymentRunId (integer), payrollGuid (uuid)
BatchJobStatusUpdatedExternal	A batch job has finished	id (uuid), status (completed or failed)

paymentRunId and payrollGuid identify the run for GET /payrolls/{payrollGuid}/paymentRuns/{paymentRunId}. id is the batch job's ID, as used by GET /batch-jobs/{jobId}.

---

Request body

Field	Type	Description
eventId	uuid	Unique per event. The same event can be delivered more than once, so use it to ignore repeats.
eventType	string	One of the event types above.
organisationId	uuid	The organisation the event belongs to.
record	string	The event's record fields, as a JSON-encoded string.

{
  "eventId": "3f7c1b9e-2d84-4a51-9f0c-6b7d8e5a1c23",
  "eventType": "PaymentRunCreatedExternal",
  "organisationId": "9a1d2c3b-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "record": "{\"paymentRunId\":1234,\"payrollGuid\":\"c9f53621-86c3-4e5a-97f7-56165388cf41\"}"
}

---

Signatures

If your endpoint has a signing secret, every request carries two headers:

Header	Value
X-Webhook-Timestamp	The time the request was sent, in Unix seconds.
X-Webhook-Signature	sha256= followed by the lowercase hex HMAC-SHA256 of {timestamp}.{body}, keyed with your signing secret.

To verify a request, compute the HMAC over the timestamp header, a . and the raw request body exactly as received, and compare it with the signature in constant time. Reject requests whose timestamp is too far from your current time. Each delivery attempt is signed afresh, so a retry carries a new timestamp.

---

Responses and retries

Your response	What happens
Any 2xx within 10 seconds	Delivered.
4xx other than 408 or 429	Treated as a rejection and not sent again.
408, 429, 5xx, a timeout or a connection failure	Sent again later, with increasing delays between attempts.

Events for your endpoint are sent in order, and a failing endpoint only delays its own events.