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, with attempts, nextAttemptAt, lastStatusCode and lastError as 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 lists replayed and skipped ids with a reason (already_due, not_found); events of another partner are not_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