Webhooks
Payroo signs and posts an event to your server when something happens to a company you act for: a company provisioned or ready for payroll, an employee onboarded, a pay run approved, lodged, accepted or rejected. Your system reacts without polling.
Credential: your partner credential (x-api-key) for the configuration routes. Deliveries themselves need no credential; you verify the signature.
Set the destination
curl -X PUT https://sandbox.payroo.com.au/api/v1/embedded/webhooks/config \
-H "x-api-key: $PAYROO_PARTNER_KEY" -H "content-type: application/json" \
-d '{ "url": "https://hooks.example.com/payroo" }'
Rules, checked at the write and again at every send: https on port 443, a public host name that resolves (no private, loopback, link-local or metadata address), and no redirects are followed. Anything else answers 422 webhook_destination_invalid.
200 with the configuration and the signing secret, shown once. Store it beside your credential, on your server. GET /webhooks/config returns the destination and never the secret (404 not_found until one is set).
Rotation. A second PUT (same or new URL) returns a new secret; the previous one keeps verifying for 24 hours (previousSecretUntil), and every delivery in that window carries two v1 signatures so either secret matches. Switch your receiver inside the window.
What arrives
POST https://hooks.example.com/payroo
Content-Type: application/json
Payroo-Event-Id: evt_01J…
Payroo-Event-Type: payrun.accepted
Payroo-Delivery-Id: dlv_01J…
Payroo-Signature: t=1794269000,v1=5f1c…e9
{
"id": "evt_01J…",
"type": "payrun.accepted",
"version": 1,
"occurredAt": "2026-11-09T22:03:20Z",
"employerId": "78cc8d2b-…",
"resource": { "type": "payrun", "id": "pr_…", "revision": 3 },
"data": { "state": "accepted" }
}
data carries state fields only, never amounts or personal data: fetch what you need from the API on your session or credential. The body is at most 256 KB.
| Event type | Fires when |
|---|---|
employer.provisioned, employer.provisioning_failed |
a provisioning operation ends |
company.updated, company.ato_notified, company.ready_for_payroll |
company setup progress |
employee.created, employee.updated, employee.invited, employee.onboarding.completed |
employees |
payrun.created, payrun.approved, payrun.reopened, payrun.lodging, payrun.accepted, payrun.rejected |
pay runs |
Verify the signature
Payroo-Signature is t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, possibly with two v1 entries during a rotation. Verify against the raw request body (before any JSON parsing), reject a t more than five minutes from now, compare in constant time, and answer 2xx within five seconds; do the real work after answering.
Node
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyPayrooSignature(
header,
rawBody,
secrets,
nowSeconds = Math.floor(Date.now() / 1000),
) {
if (!header) return false;
const fields = header.split(',').map((f) => f.trim().split('='));
const t = Number(fields.find(([k]) => k === 't')?.[1]);
const sigs = fields.filter(([k]) => k === 'v1').map(([, v]) => v);
if (!Number.isFinite(t) || sigs.length === 0 || Math.abs(nowSeconds - t) > 300) return false;
return secrets.some((secret) => {
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return sigs.some(
(s) =>
s.length === expected.length &&
timingSafeEqual(Buffer.from(s, 'hex'), Buffer.from(expected, 'hex')),
);
});
}
// Express: keep the raw body
app.post('/payroo', express.raw({ type: 'application/json' }), (req, res) => {
const ok = verifyPayrooSignature(
req.get('Payroo-Signature'),
req.body.toString('utf8'),
[process.env.PAYROO_WEBHOOK_SECRET, process.env.PAYROO_WEBHOOK_SECRET_PREVIOUS].filter(Boolean),
);
if (!ok) return res.status(401).end();
res.status(202).end(); // answer first
queue(JSON.parse(req.body)); // then work
});
If you use @payroo-group/embedded-core, verifyWebhookSignature(secrets, header, rawBody) is the same check, built on WebCrypto, with a reason (missing, malformed, stale, mismatch) when it fails.
Python
import hmac, hashlib, time
def verify_payroo_signature(header: str | None, raw_body: bytes, secrets: list[str], now: int | None = None) -> bool:
if not header:
return False
fields = dict(); sigs = []
for part in header.split(","):
k, _, v = part.strip().partition("=")
if k == "v1": sigs.append(v)
else: fields[k] = v
try: t = int(fields["t"])
except (KeyError, ValueError): return False
if not sigs or abs((now or int(time.time())) - t) > 300:
return False
for secret in secrets:
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
if any(hmac.compare_digest(s, expected) for s in sigs):
return True
return False
PHP
function verifyPayrooSignature(?string $header, string $rawBody, array $secrets, ?int $now = null): bool {
if (!$header) return false;
$t = null; $sigs = [];
foreach (explode(',', $header) as $part) {
[$k, $v] = array_pad(explode('=', trim($part), 2), 2, null);
if ($k === 't') $t = (int) $v; elseif ($k === 'v1') $sigs[] = $v;
}
if (!$t || !$sigs || abs(($now ?? time()) - $t) > 300) return false;
foreach ($secrets as $secret) {
$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
foreach ($sigs as $s) if (hash_equals($expected, $s)) return true;
}
return false;
}
// $rawBody = file_get_contents('php://input');
Retries, deliveries and replay
A non-2xx answer, a timeout or a connection error is retried at 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours, then the delivery is dead. Process by id (the event id) so a retry of an event you already handled is a no-op.
GET /webhooks/deliveries?state=dead&cursor=: your deliveries newest first, withattempts,nextAttemptAt,lastStatusCodeandlastErroras a class (timeout,dns,tls,http_4xx,http_5xx,destination_invalid), never your server's response body.POST /webhooks/replay { eventIds: [...] }(up to 100): queues one new attempt per event for your dead or delivered deliveries. The answer listsreplayedandskippedids with a reason (already_due,not_found); events of another partner arenot_found, never revealed.
What you should see
After PUT /webhooks/config, provision a sandbox company: an employer.provisioned delivery reaches your receiver within a minute, your verification passes, and GET /webhooks/deliveries shows it delivered with attempts: 1. Then rotate: a second PUT returns a new secret, the next deliveries carry two v1 entries, and both your old and new secrets verify until previousSecretUntil.
Errors you may see
| Status and code | Meaning | Next action |
|---|---|---|
422 webhook_destination_invalid |
not https, wrong port, private or unresolvable host | use a public https destination on 443 |
404 not_found on GET /webhooks/config |
no destination yet | PUT one |
deliveries dead |
six retries failed | fix the receiver, then replay the event ids |