Know the moment your data changes.

01What webhooks give you

A webhook endpoint is a URL you own. When payroll data changes inside one of your clients' accounts, we build a small JSON event describing what changed and POST it to that URL. You choose which of the nine event types you want, so a listener that only cares about new employees never sees pay traffic.

Before you start

• Your Lightning Payroll account must be an API admin account. If it is not, every webhook call returns 403 with {"detail": "Forbidden"}. See the API Admin Setup and Management Guide.
• You need a bearer token for your own API admin account, not one issued to you for a client. A token minted for an end customer resolves to that customer and gets 403 here. An interactive dashboard session works, as does an OAuth access token whose subject is your own API admin account.
• Your listener must be reachable from the public internet on a routable address. This is enforced, not advisory. See Registering an endpoint.

You can also manage everything on this page from the API Management section of your Lightning Payroll admin dashboard, on the Webhooks tab, including a browsable delivery history with the exact payload of every attempt. The dashboard and these endpoints act on the same records.

02The event catalogue

Nine event types across three entities. Subscribe by naming each one you want. There is no wildcard, so "events": ["*"] is rejected; list the strings explicitly.

• 1An employee who is soft deleted arrives as employee.deleted, not as an employee.updated that happens to flip a flag. Subscribe to employee.deleted if you care about removals.
• 2Pay events only fire for a completed pay, and which one you get depends on how it was completed. A pay inserted already complete in a single operation, which is what the API pay-creation endpoints do, arrives as pay.created. A pay saved as a draft and completed later, which is what the Complete Pay Run action in the app does, arrives as pay.updated with no preceding pay.created, because writes to an incomplete pay are suppressed. Subscribe to both if you want to know when a pay is finalised. A draft pay produces nothing at all, so seeing no events while a pay run is still open is the gate working correctly rather than a broken registration.

The authoritative list is always returned as availableEvents by GET /api/webhooks, generated from the server's own catalogue. Read it at runtime rather than hardcoding this table if you want to pick up new event types automatically.

03Registering an endpoint

POST /api/webhooks
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "url": "https://yourapp.example.com/hooks/lightning-payroll",
  "events": ["employee.created", "employee.updated", "pay.created", "pay.updated"],
  "description": "Production employee sync",
  "is_active": true
}

{
  "message": "Webhook created",
  "webhook": {
    "id": 14,
    "url": "https://yourapp.example.com/hooks/lightning-payroll",
    "events": ["employee.created", "employee.updated", "pay.created", "pay.updated"],
    "isActive": true,
    "description": "Production employee sync",
    "secret": "xW9c...redacted...q2Zt",
    "createdAt": "2026-08-07T04:11:07"
  }
}

Request fields

Which URLs are rejected

We resolve your hostname and check every address it answers with. Anything that is not globally routable is refused with 422. This is checked when you register and again every time we send, so a hostname that later re-points at an internal address stops being delivered to rather than becoming a way into our network.

Because of this, you cannot point a registered webhook at localhost while developing. Use a tunnelling service that gives you a public hostname, or run your listener on a host with a real public address.

At registration a rejection is an immediate 422. At send time there is no response to reject, so a URL that has since become unroutable simply fails that attempt: the delivery moves to retry and the reason appears in lastError in the delivery log.

Rotating the secret

Send regenerate_secret on its own. The new value comes back once, as webhook.secret.

PATCH /api/webhooks/14
Authorization: Bearer YOUR_ACCESS_TOKEN

{ "regenerate_secret": true }

Pausing without losing history

PATCH with {"is_active": false} to stop deliveries and keep the endpoint and its delivery log. DELETE removes the endpoint and its entire delivery history, which cannot be recovered, so export anything you need first.

04What a delivery looks like

Every delivery is a POST with a JSON body and five headers.

{
  "id": "9f2b1c84-6d1e-4a7f-9c0b-2e5d7a3f8b41",       // event id, changes per payload
  "type": "employee.updated",
  "createdAt": "2026-08-07T04:11:07.482913",           // UTC, no offset or Z
  "customerId": 192601,                              // YOUR CLIENT, not you
  "entity": { "type": "employee", "id": 4412 },
  "data": {
    "id": 4412,
    "first_name": "Alice",
    "surname": "Nguyen",
    // ... the full entity, same shape as the REST API returns
  }
}

05Verifying the signature

Anyone can POST to your URL. The signature is how you know a delivery is really from us. Verify it on every request and reject anything that does not match.

We concatenate the timestamp, a literal dot, and the exact request body, then HMAC that string with your endpoint's secret using SHA-256, and hex encode the result.

const crypto = require('crypto');
const express = require('express');
const app = express();

// Raw body, NOT express.json(). Re-serialising breaks the signature.
app.post('/hooks/lightning-payroll',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const timestamp = req.get('X-LP-Timestamp');
    const received  = req.get('X-LP-Signature');
    const body      = req.body;  // a Buffer

    const expected = crypto
      .createHmac('sha256', process.env.LP_WEBHOOK_SECRET)
      .update(timestamp + '.')
      .update(body)
      .digest('hex');

    const a = Buffer.from(expected, 'utf8');
    const b = Buffer.from(received || '', 'utf8');
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.sendStatus(401);
    }

    // Reject stale deliveries. The timestamp is signed, so this blocks replays.
    const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
    if (ageSeconds > 300) return res.sendStatus(401);

    const event = JSON.parse(body.toString('utf8'));

    // Dedup on the PAIR: an untried delivery id can be re-armed with new data.
    enqueueForProcessing(req.get('X-LP-Delivery-Id'), event.id, event);

    res.sendStatus(200);  // ack fast, work later
  });

import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["LP_WEBHOOK_SECRET"].encode()


@app.route("/hooks/lightning-payroll", methods=["POST"])
def lightning_payroll_hook():
    timestamp = request.headers.get("X-LP-Timestamp", "")
    received = request.headers.get("X-LP-Signature", "")

    # request.get_data() is the raw body. Do NOT use request.json here.
    body = request.get_data()
    signed = timestamp.encode() + b"." + body
    expected = hmac.new(SECRET, signed, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, received):
        abort(401)

    # Reject stale deliveries. The timestamp is signed, so this blocks replays.
    if abs(time.time() - int(timestamp)) > 300:
        abort(401)

    event = request.get_json()

    # Dedup on the PAIR: an untried delivery id can be re-armed with new data.
    delivery_id = request.headers.get("X-LP-Delivery-Id")
    enqueue_for_processing(delivery_id, event["id"], event)

    return "", 200  # ack fast, work later

<?php
// php://input is the raw body. Never re-encode the decoded array.
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_LP_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_LP_SIGNATURE'] ?? '';

$expected = hash_hmac('sha256', $timestamp . '.' . $body, getenv('LP_WEBHOOK_SECRET'));

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

// Reject stale deliveries. The timestamp is signed, so this blocks replays.
if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);

// Dedup on the PAIR: an untried delivery id can be re-armed with new data.
enqueue_for_processing($_SERVER['HTTP_X_LP_DELIVERY_ID'], $event['id'], $event);

http_response_code(200);  // ack fast, work later

06Delivery lifecycle

Each delivery moves through a small set of states. These are the same status values you see in the dashboard's delivery history and in GET /api/webhooks/deliveries, with the same colours.

What counts as success

• Any status in the 200 to 299 range. Nothing else counts.
• Redirects are not followed. A 301 or 302 is a failure, so register the final URL rather than a redirector.
• We wait 10 seconds. A slower response is a timeout and becomes a retry, even if your handler eventually finished the work.
• Your response body is recorded, truncated, so returning a short diagnostic string is genuinely useful when you later inspect a failure.

07Retries and timing

A failed delivery is retried with exponential backoff, doubling each time, for a maximum of 8 attempts. Bars below are drawn to scale, so you can see how quickly the gaps stretch out.

If the eighth attempt also fails, the delivery becomes failed and is never retried. From the first attempt to the last is a little over one hour, which is the window you have to notice and fix an outage before events start being lost.

08What a good listener does

• 01

  Verify the signature before anything else

  Reject unsigned or mis-signed requests with a 401 and do no work. Your URL is public, so this is the only thing standing between your database and anyone who guesses the path.

• 02

  Return 2xx fast, then do the work

  You have a 10 second budget. Persist the event, return 200, and process asynchronously. Doing the real work inline is the most common cause of avoidable retries, and a retry storm on your slowest endpoint will not help.

• 03

  Be idempotent on the delivery id and payload id together

  A retry re-sends the same X-LP-Delivery-Id, so skip work only when the payload id also matches something you have processed. A familiar delivery id carrying a new payload id is a newer version of that entity, not a duplicate, and dropping it loses data.

• 04

  Do not assume ordering

  Deliveries are independent and retries reorder things by design, so an employee.updated can arrive before the employee.created that failed twice. Treat each event as "this entity changed, here is its current state" and reconcile, rather than replaying a sequence.

• 05

  Trust the API over the payload for critical reads

  data is a snapshot from when the payload was built. For anything you are about to act on financially, re-fetch the record so you are working from current state. Remember the REST routes are company-scoped, so you need a company id as well as entity.id, and you re-fetch with the token you hold for that end customer.

• 06

  Tolerate unknown fields and unknown events

  New fields can appear inside data, and new event types can be added to the catalogue. Ignore what you do not recognise instead of failing the request, or a future addition turns into an outage.

• 07

  Keep each client's OAuth authorization alive

  Changes you make through the API are attributed to you by the access token you present, so your own calls always reach your endpoint while that client's authorization is current. Changes the customer makes for themselves, in the web app or the desktop app, carry no partner in context, so they are attributed to that customer's most recently authorized integration. Two consequences worth designing for: if a client's authorization is revoked and never replaced, their changes stop arriving, silently and with nothing in the delivery log, because no delivery is ever created; and where a customer has authorized more than one integration, the changes they make themselves are attributed to one of them rather than to all. Treat the event stream as a fast path rather than a guaranteed-complete ledger, and reconcile against the REST API when you need certainty.

09Endpoint reference

All five endpoints require an API admin bearer token and act only on your own records. They are documented interactively, with a Try it out button, in the Admin section of the API reference.

Errors

10Troubleshooting