Webhooks

Overview

Webhooks let your systems react to changes in Corebill without polling. When a subscribed event happens, Corebill sends an HTTP POST with a JSON body to your endpoint, signed with the destination secret.

Events fire the same way whether the change came from the dashboard, the REST API, an automation, Stripe or the AI Agent. Destinations are configured per company in Settings > Developers > Webhooks: URL, events, custom headers, signing secret and the delivery log.

Available Events

Customers

Quotes

Invoices

Payments

Services and products

Subscriptions

Requires the Subscriptions module.

Projects and tasks

Requires the Projects module.

Expenses

Requires the Expenses module.

Vendors

Requires the Vendors module.

Inventory

Requires the Inventory module.

Purchases

Requires the Purchases module.

Cash

Requires the Cash module.

Point of sale

Requires the Point of sale module.

Work orders

Requires the Work orders module.

Payload

 1{
 2  "id": "evt_8f2c1a9b7d3e4f56",
 3  "event": "invoice.paid",
 4  "created_at": "2026-10-11T15:30:00.000Z",
 5  "webhook_id": "wh_a1b2c3d4e5f6",
 6  "data": {
 7    "id": "inv_b2c3d4e5f6g7h8i9",
 8    "invoice_number": "INV-2026-000042",
 9    "customer_id": "cus_a1b2c3d4e5f6g7h8",
10    "issue_date": "2026-10-11",
11    "due_date": "2026-11-10",
12    "currency": "USD",
13    "subtotal": 1500,
14    "discount_amount": 0,
15    "tax_amount": 270,
16    "total": 1770,
17    "amount_paid": 1770,
18    "amount_due": 0,
19    "status": "paid",
20    "lines": [
21      {
22        "id": "dit_a1b2c3d4e5f6",
23        "item_id": "itm_e5f6g7h8i9j0k1l2",
24        "name": "Web Development - Senior",
25        "quantity": 10,
26        "unit_price": 150,
27        "total": 1500
28      }
29    ],
30    "created_at": "2026-10-11T15:30:00.000Z",
31    "updated_at": "2026-10-11T15:30:00.000Z"
32  },
33  "metadata": {}
34}

id is the event id (the same on every retry), event the event type and data the resource. Core resources (customers, quotes, invoices, items, expenses) use the same shape as the REST API. metadata carries the custom fields of customers, quotes and invoices. Test events include "test": true.

Headers

Verifying the Signature

Always verify the signature before trusting a webhook. Use the raw request body (do not parse and re-stringify it), compare in constant time and reject timestamps older than 5 minutes to block replays.

 1import crypto from 'node:crypto'
 2import express from 'express'
 3
 4const app = express()
 5const SECRET = process.env.COREBILL_WEBHOOK_SECRET // whsec_...
 6
 7// Corebill signs "<t>.<raw body>": use express.raw, not express.json
 8app.post('/webhooks/corebill', express.raw({ type: 'application/json' }), (req, res) => {
 9  const header = req.get('Corebill-Signature') || ''
10  const parts = header.split(',')
11  const t = parts.find((p) => p.startsWith('t='))?.slice(2)
12  const signatures = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3))
13
14  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.${req.body}`).digest('hex')
15  const valid = signatures.some(
16    (s) => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected))
17  )
18  // Reject invalid signatures or ones older than 5 minutes
19  if (!valid || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400)
20
21  const event = JSON.parse(req.body)
22  // Respond fast and process later; deduplicate by event.id
23  console.log(event.event, event.data.id)
24  res.sendStatus(200)
25})
26
27app.listen(3000)

Responding

Return a 2xx status code within 10 seconds. Anything else, a redirect or a timeout counts as a failure. Keep handlers fast: store the event, answer 200 and process it in the background.

Retries

After 5 failed attempts the delivery stays as failed. You can resend any delivery from the destination log; a resend replaces a pending automatic retry.

Idempotency

The same event can arrive more than once (retries, manual resends). Use the envelope id (or the X-Event-Id header) as an idempotency key: if you already processed evt_..., ignore it.

Secret Rotation

Rotate the signing secret from the destination detail. For the next 24 hours every event carries two v1 signatures (new and previous secret), so you can deploy the new secret without losing events. Accept the event if any v1 matches.

Testing

1. Open Settings > Developers > Webhooks and pick a destination
2. Click Send test event and choose any event of the catalog
3. Corebill sends the example payload with "test": true and shows the status code and response time. Test events are not retried

The delivery log keeps every attempt with the payload, the headers sent (custom header values are hidden), the response and the response headers.