Skip to Content
Developers

Webhooks

Receive events from Billleaf as they happen.

In Settings → Webhooks (Pro and Team), add an endpoint URL and choose which events it receives. Billleaf then sends an HTTPS POST for each event. Use Send test event to try it, and the delivery log to see every request and response.

Events

EventWhendata.object
client.createdA client is addedClient
quote.acceptedA quote is accepted (in the app or the portal)Quote
quote.declinedA quote is declinedQuote
contract.signedA contract is signedContract
invoice.issuedAn invoice is issuedInvoice
invoice.sentAn invoice is emailedInvoice
invoice.paidA payment settles the invoice in fullInvoice
invoice.voidedAn invoice is voidedInvoice
credit_note.issuedA credit note is issuedCredit note
payment.recordedA payment is recorded (or a proof confirmed)Payment
payment_proof.submittedA client uploads a payment proofProof summary
timesheet.submittedA member submits a week of time for approvalTimesheet approval
timesheet.approvedA submitted week is approvedTimesheet approval
timesheet.rejectedA week is sent back (or an approved one reopened)Timesheet approval
pingSend test event{ message }

Objects have the same shape as the API reference responses, as they were when the event happened.

The request

POST /your/endpoint
Content-Type: application/json
User-Agent: Billleaf-Webhooks/1.0
Billleaf-Event: invoice.paid
Billleaf-Delivery: 0193…
Billleaf-Signature: t=1763300000,v1=5f2b…

{"id":"evt_…","type":"invoice.paid","createdAt":"2026-11-16T10:00:00.000Z","workspaceId":"…","data":{"object":{…}}}

Reply with any 2xx status within 10 seconds. Anything else — another status, a timeout or a redirect — is retried 7 more times, starting after 1 minute and doubling (about 2 hours in all). After 10 events in a row fail, the webhook is turned off and workspace owners are emailed.

Delivery is at least once and not ordered: use the event id to ignore duplicates (a manual Resend keeps the same id).

Verifying the signature

v1 is the hex HMAC-SHA256 of "<t>.<raw body>" using your webhook's signing secret (shown when you create the webhook, or rotate its secret). Check it before trusting a request, and reject old timestamps:

import { createHmac, timingSafeEqual } from "node:crypto"

export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")))
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex")
  const fresh =
    Math.abs(Date.now() / 1000 - Number(parts.t)) <= toleranceSeconds
  return (
    fresh &&
    expected.length === parts.v1?.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
  )
}

Use the body exactly as received, before parsing it as JSON.

Security

Webhook URLs must use https:// and point to a public address. Billleaf doesn't follow redirects.

On this page