Register an HTTP endpoint for JSON event deliveries, with retries and delivery logs. Signatures require a configured secret.

Webhooks let an external system react to what happens in Arche without polling the API. This guide covers setting up an endpoint from Settings → Webhooks (/settings/webhooks), how deliveries are signed and retried, and where to check what actually went out.

Who can manage webhooks

Managing webhooks requires manage_settings and the Webhooks module licence. The Roles & Permissions page displays the permission matrix; access follows granted permissions rather than a role's display name.

Setting up an endpoint

From the Endpoints tab, click New Webhook and provide:

Field	Notes
Name	A label for your own reference.
URL	Must be a valid HTTPS/HTTP URL. Arche checks it can't resolve to a private, loopback, or cloud-metadata address (`169.254.169.254` and similar): internal infrastructure is never a valid delivery target.
Events	A comma-separated list of event names you want delivered, or `*` to receive everything sent to your company.
Retry count	0–10. How many additional attempts after the first, capped at 5 regardless of what you set.
Timeout	1,000–120,000 ms per attempt.

The API additionally accepts a signing secret and custom headers; the current web form does not expose either field. Secrets are stored encrypted and omitted from responses. Reserved transport and X-Webhook-* headers are filtered from custom headers. Use the event names in the catalog below: the form's example placeholder omits their domain prefixes and is not a valid catalog.

Verifying a delivery came from Arche

Deliveries carry event, id, timestamp and attempt headers. Signature headers are included only when a signing secret is configured:

X-Webhook-Event:     hr.employee.created
X-Webhook-Id:        <webhook id>
X-Webhook-Timestamp: <unix seconds>
X-Webhook-Attempt:   1
X-Webhook-Signature:    sha256=<hmac of the raw request body>
X-Webhook-Signature-V2: sha256=<hmac of "{timestamp}.{body}">

If you set a secret, both signature headers are HMAC-SHA256, computed over the exact bytes sent. Recompute the same HMAC on your side and compare: X-Webhook-Signature covers the body alone, and X-Webhook-Signature-V2 binds the timestamp into the signed value as well, so a captured delivery can't be replayed later under a different timestamp. Prefer the V2 header for new integrations and reject anything outside a reasonable clock-skew window of the timestamp it carries.

Delivery, retries, and failure handling

A delivery is a POST of the event payload as JSON. Only failures that look transient are retried: a network error or timeout, or an HTTP 5xx, 408, or 429 response. A 4xx (other than 408/429) is treated as a permanent rejection and isn't retried. Redirects are never followed: a 3xx response counts as a failure rather than a hop to a different URL.

Retries use exponential backoff with a little random jitter, up to the retry count you configured (5 attempts maximum on top of the first, however high you set it). If a webhook racks up 25 consecutive failed deliveries, Arche switches it off automatically (isActive flips to false) so a dead endpoint doesn't keep getting hit; you'll need to re-enable it from the endpoint's row once the destination is fixed.

Delivery Logs

The Delivery Logs tab lists attempts with event, outcome (success, failed or timeout), HTTP status, duration and timestamp. Retries produce additional attempt rows. Use the log to inspect failures and the recorded response body.

Testing a webhook

Click the play icon on an endpoint's row to send a test delivery: a synthetic webhook.test event with a fixed payload, signed and delivered exactly like a real one. This is the reliable way to confirm your endpoint is reachable and that your signature verification is implemented correctly before you depend on it for anything live.

Platform-level webhooks

Platform administrators can also register webhooks that aren't tied to a single company, from a separate platform-scope settings screen. A platform webhook fires for matching events across every tenant, tagged with the originating company's id in the payload.

FAQ

What event names should I subscribe to? Subscribe to any of the events in the catalog below, or * for all of them. Run a test delivery first to prove your endpoint and signature check work, then watch the Delivery Logs tab as real events start arriving.

Event catalog

These business events are delivered today. Payloads are deliberately thin: record ids, statuses, and counts, never names, contact details, or money amounts. A receiver that needs more detail calls back into the API with its own credentials.

Event	Payload fields
`hr.employee.created`	`employeeId`, `employeeNumber`
`hr.employee.updated`	`employeeId`, `changes` (list of change types)
`hr.employee.terminated`	`employeeId`, `terminationDate`
`time.leave.requested`	`leaveRequestId`, `employeeId`, `totalDays`
`time.leave.approved`	`leaveRequestId`, `employeeId`, `totalDays`
`time.leave.rejected`	`leaveRequestId`, `employeeId`, `totalDays`
`time.leave.cancelled`	`leaveRequestId`, `employeeId`, `totalDays`
`payroll.pay_run.created`	`payRunId`
`payroll.pay_run.calculated`	`payRunId`, `employeeCount`
`payroll.pay_run.approved`	`payRunId`
`payroll.pay_run.completed`	`payRunId`
`payroll.pay_run.reversed`	`payRunId`
`payroll.payslip.generated`	`payRunId`, `count`

Business-event deliveries contain event, timestamp (ISO 8601), companyId, _companyId and data holding the allowlisted fields above. eventId is included when the originating event supplies one; absent payload fields are omitted. Events outside this business-event catalog are not forwarded by the listener. Manual test deliveries use the separate webhook.test shape.

Can I see my signing secret again after I save it? No. The API only ever tells you whether a secret is configured, never the value. If you lose it, set a new one. Your endpoint just needs to be updated to verify with the new secret.

My endpoint is getting real traffic: how do I confirm it's a genuine delivery and not somebody else? Verify X-Webhook-Signature-V2 using your secret before trusting the payload. A request without a valid signature, or with a stale timestamp, didn't come from Arche's dispatcher (or it did, but the secret configured on your end doesn't match, worth checking).

Why did my webhook stop firing? Check its failure count on the Endpoints tab. Twenty-five consecutive failures disables a webhook automatically. Fix the destination, then flip it back on.

Does the test button count toward my retry/failure numbers? Yes. A test delivery goes through the same dispatch, logging, and failure-counting path as a real one, so a broken endpoint that fails a bunch of manual tests can trip the auto-disable threshold too.