Webhook Event Types

Invoice AI fires a webhook event every time a significant action occurs on an invoice. Your registered webhook endpoints receive a signed HTTP POST with a JSON payload describing what happened and which invoice was affected.

All event types

Event type	Trigger
`invoice.created`	A draft invoice was created.
`invoice.updated`	A draft invoice was edited (fields changed, items added/removed).
`invoice.finalized`	An invoice was finalized and its status moved to `open`. An invoice number was assigned.
`invoice.emailed`	An invoice was successfully emailed to the customer.
`invoice.email_failed`	An invoice email bounced or was rejected by the recipient’s mail server.
`invoice.viewed`	A customer opened the invoice’s public link.
`invoice.downloaded`	A customer downloaded the invoice PDF.
`invoice.paid`	An invoice was marked as paid.
`invoice.voided`	An invoice was voided.

There is no invoice.overdue event. Overdue status is computed from due_date at read time — it is never stored — so there is no discrete moment when it transitions. To find overdue invoices, poll GET /api/v1/invoices?status=overdue.

Payload structure

Every event payload follows the same envelope:

{
  "type": "<event_type>",
  "data": {
    "object": { ...invoice object... }
  }
}

string

The event type string, e.g. "invoice.paid". Always present.

object

Container for the event data.

Show data fields

object

The full invoice object at the time the event was fired. The shape matches the invoice resource returned by GET /api/v1/invoices/:id, including all line items under lines.data.

Event payload examples

`invoice.paid`

Fired when an invoice is marked paid. The paid_at timestamp is set and status changes to "paid".

{
  "type": "invoice.paid",
  "data": {
    "object": {
      "id": "in_01hxyz1234567890abcdefghij",
      "object": "invoice",
      "number": "INV-0042",
      "status": "paid",
      "customer": "cus_01hxyz1234567890abcdefghij",
      "currency": "USD",
      "collection_method": "send_invoice",
      "issue_date": "2024-06-01",
      "due_date": "2024-06-15",
      "description": "June consulting engagement",
      "footer": "Payment due within 14 days. Thank you for your business.",
      "subtotal": 45000,
      "discount": 2250,
      "taxable": 42750,
      "tax": 3634,
      "total": 46384,
      "amount_due": 0,
      "amount_in_words": "Four Hundred Sixty Three Dollars and Eighty Four Cents",
      "public_url_token": "tok_AbCdEfGh1234",
      "finalized_at": "2024-06-01T09:15:00.000Z",
      "paid_at": "2024-06-10T14:32:00.000Z",
      "voided_at": null,
      "void_reason": null,
      "created": "2024-05-30T11:00:00.000Z",
      "updated": "2024-06-10T14:32:00.000Z",
      "lines": {
        "data": [
          {
            "id": "ii_01hxyz1234567890abcdefghij",
            "object": "invoiceitem",
            "price": "price_01hxyz1234567890abcdefghij",
            "product": "prod_01hxyz1234567890abcdefghij",
            "description": "Professional Consulting",
            "quantity": 3,
            "unit": "HRS",
            "unit_amount": 15000,
            "amount": 42750,
            "discount_percent": 5,
            "tax_rate": 8.5,
            "tax_amount": 3634
          }
        ]
      }
    }
  }
}

`invoice.email_failed`

Fired when an invoice email bounced or was rejected. The meta field on the underlying event row may contain error details from the mail provider. Use this event to detect delivery failures and notify the customer through an alternative channel.

{
  "type": "invoice.email_failed",
  "data": {
    "object": {
      "id": "in_01hxyz9876543210zyxwvutsrq",
      "object": "invoice",
      "number": "INV-0043",
      "status": "open",
      "customer": "cus_01hxyz9876543210zyxwvutsrq",
      "currency": "USD",
      "collection_method": "send_invoice",
      "issue_date": "2024-06-05",
      "due_date": "2024-06-19",
      "description": null,
      "footer": null,
      "subtotal": 120000,
      "discount": 0,
      "taxable": 120000,
      "tax": 10200,
      "total": 130200,
      "amount_due": 130200,
      "amount_in_words": "One Thousand Three Hundred Two Dollars and Zero Cents",
      "public_url_token": "tok_ZyXwVuTs5678",
      "finalized_at": "2024-06-05T10:00:00.000Z",
      "paid_at": null,
      "voided_at": null,
      "void_reason": null,
      "created": "2024-06-04T16:00:00.000Z",
      "updated": "2024-06-05T10:05:00.000Z",
      "lines": {
        "data": [
          {
            "id": "ii_01hxyzabcdef1234567890ghij",
            "object": "invoiceitem",
            "price": null,
            "product": null,
            "description": "Annual Software License",
            "quantity": 1,
            "unit": "NOS",
            "unit_amount": 120000,
            "amount": 120000,
            "discount_percent": 0,
            "tax_rate": 8.5,
            "tax_amount": 10200
          }
        ]
      }
    }
  }
}

When you receive invoice.email_failed:

Retrieve the customer’s contact details with GET /api/v1/customers/:id.
Verify or correct the email address, then re-send through the dashboard or the send endpoint.
Consider notifying your team via a support queue so a human can follow up.

`invoice.finalized`

Fired when a draft is finalized. An invoice number is assigned and status moves to "open".

{
  "type": "invoice.finalized",
  "data": {
    "object": {
      "id": "in_01hxyz1234567890abcdefghij",
      "object": "invoice",
      "number": "INV-0044",
      "status": "open",
      "customer": "cus_01hxyz1234567890abcdefghij",
      "currency": "USD",
      "collection_method": "send_invoice",
      "issue_date": "2024-06-10",
      "due_date": "2024-06-24",
      "description": null,
      "footer": null,
      "subtotal": 50000,
      "discount": 0,
      "taxable": 50000,
      "tax": 0,
      "total": 50000,
      "amount_due": 50000,
      "amount_in_words": "Five Hundred Dollars and Zero Cents",
      "public_url_token": "tok_MnOpQrSt9012",
      "finalized_at": "2024-06-10T08:00:00.000Z",
      "paid_at": null,
      "voided_at": null,
      "void_reason": null,
      "created": "2024-06-09T17:00:00.000Z",
      "updated": "2024-06-10T08:00:00.000Z",
      "lines": {
        "data": []
      }
    }
  }
}

`invoice.voided`

Fired when an invoice is voided. status becomes "voided", voided_at is set, and amount_due drops to 0.

{
  "type": "invoice.voided",
  "data": {
    "object": {
      "id": "in_01hxyz1234567890abcdefghij",
      "object": "invoice",
      "number": "INV-0041",
      "status": "voided",
      "customer": "cus_01hxyz1234567890abcdefghij",
      "currency": "USD",
      "collection_method": "send_invoice",
      "issue_date": "2024-05-01",
      "due_date": "2024-05-15",
      "description": null,
      "footer": null,
      "subtotal": 20000,
      "discount": 0,
      "taxable": 20000,
      "tax": 0,
      "total": 20000,
      "amount_due": 0,
      "amount_in_words": "Two Hundred Dollars and Zero Cents",
      "public_url_token": "tok_GhIjKlMn3456",
      "finalized_at": "2024-05-01T09:00:00.000Z",
      "paid_at": null,
      "voided_at": "2024-05-20T11:00:00.000Z",
      "void_reason": "Duplicate invoice",
      "created": "2024-04-30T15:00:00.000Z",
      "updated": "2024-05-20T11:00:00.000Z",
      "lines": {
        "data": []
      }
    }
  }
}

Signature verification

All deliveries are signed using the Standard Webhooks HMAC-SHA256 scheme. Three headers travel with every request:

Header	Description
`webhook-id`	Unique delivery ID, stable across retries.
`webhook-timestamp`	Unix timestamp (seconds) of dispatch.
`webhook-signature`	`v1,<base64 HMAC-SHA256>` over `"{id}.{timestamp}.{body}"`.

The signed string is constructed as:

{webhook-id}.{webhook-timestamp}.{raw_request_body}

The HMAC key is derived from your whsec_… secret by stripping the whsec_ prefix and base64url-decoding the remainder.

Node.js verification example

import { createHmac, timingSafeEqual } from 'crypto';

/**
 * Verify an incoming Invoice AI webhook delivery.
 *
 * @param {string} rawBody     - The raw (unparsed) request body as a string.
 * @param {object} headers     - Request headers object (lowercase keys).
 * @param {string} secret      - Your whsec_… signing secret.
 * @throws {Error}             - If the signature is invalid or the timestamp is stale.
 */
function verifyInvoiceAIWebhook(rawBody, headers, secret) {
  const webhookId        = headers['webhook-id'];
  const webhookTimestamp = headers['webhook-timestamp'];
  const webhookSignature = headers['webhook-signature'];

  if (!webhookId || !webhookTimestamp || !webhookSignature) {
    throw new Error('Missing webhook signature headers.');
  }

  // Reject deliveries with a timestamp older than 5 minutes (Standard Webhooks default).
  const now       = Math.floor(Date.now() / 1000);
  const timestamp = Number(webhookTimestamp);
  if (!Number.isFinite(timestamp) || Math.abs(now - timestamp) > 300) {
    throw new Error('Webhook timestamp is out of tolerance (> 5 minutes).');
  }

  // Build the signed content string.
  const signedContent = `${webhookId}.${webhookTimestamp}.${rawBody}`;

  // Derive the HMAC key from the whsec_ secret.
  const secretKey = Buffer.from(secret.replace(/^whsec_/, ''), 'base64url');

  // Compute the expected signature.
  const expectedMac = createHmac('sha256', secretKey)
    .update(signedContent)
    .digest('base64');
  const expected = `v1,${expectedMac}`;

  // The header may carry multiple space-separated signatures during key rotation.
  const presented = webhookSignature.split(' ').filter(Boolean);
  const matched = presented.some((candidate) => {
    if (candidate.length !== expected.length) return false;
    return timingSafeEqual(Buffer.from(candidate), Buffer.from(expected));
  });

  if (!matched) {
    throw new Error('Webhook signature verification failed.');
  }
}

Express.js handler example

import express from 'express';
import { verifyInvoiceAIWebhook } from './verify.js'; // the function above

const app = express();

// Use express.raw() so req.body contains the raw Buffer — never parse JSON
// before verifying the signature, as JSON.parse + re-stringify can alter whitespace
// and invalidate the HMAC.
app.post(
  '/webhooks/invoice-ai',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const rawBody = req.body.toString('utf8');

    try {
      verifyInvoiceAIWebhook(
        rawBody,
        req.headers,
        process.env.INVOICE_AI_WEBHOOK_SECRET
      );
    } catch (err) {
      console.error('Webhook verification failed:', err.message);
      return res.status(400).send('Bad signature');
    }

    const event = JSON.parse(rawBody);

    switch (event.type) {
      case 'invoice.paid':
        // Mark order as paid in your database
        handleInvoicePaid(event.data.object);
        break;

      case 'invoice.email_failed':
        // Alert your support team
        handleEmailFailed(event.data.object);
        break;

      case 'invoice.voided':
        // Reverse any provisional accounting entries
        handleInvoiceVoided(event.data.object);
        break;

      default:
        // Acknowledge events you don't handle so retries stop
        console.log(`Unhandled event type: ${event.type}`);
    }

    // Respond quickly — process async if needed
    res.status(200).send('OK');
  }
);

You must use timingSafeEqual (or an equivalent constant-time comparison) when comparing signatures. A standard === check is vulnerable to timing side-channel attacks.

Use the webhook-id as an idempotency key in your handler. If your server crashes after processing but before responding 200, Invoice AI will retry with the same webhook-id. Deduplicate on this value to avoid processing the same event twice.

Secret rotation

To rotate your webhook signing secret:

Delete the existing endpoint (DELETE /api/v1/webhook-endpoints/:id) and immediately create a new one with the same URL (POST /api/v1/webhook-endpoints). The creation response includes your new whsec_… secret.
Update the secret value in your server’s configuration before any new deliveries arrive on the new endpoint.
Any in-flight deliveries against the old endpoint will exhaust their retry schedule and stop; the new endpoint starts with a clean slate.

Because the webhook-signature header may carry multiple space-separated signatures, you can verify against both the old and new secret during your deployment window to avoid dropping events mid-rotation. Pass both secrets through your verification logic and accept the delivery if either matches.

Overview

Invoices

Customers & Catalog

Webhooks

Invoice AI Webhook Event Types and Payload Reference

Webhook Event Types

All event types

Payload structure

Event payload examples

`invoice.paid`

`invoice.email_failed`

`invoice.finalized`

`invoice.voided`

Signature verification

Node.js verification example

Express.js handler example

Secret rotation

​Webhook Event Types

​All event types

​Payload structure

​Event payload examples

​invoice.paid

​invoice.email_failed

​invoice.finalized

​invoice.voided

​Signature verification

​Node.js verification example

​Express.js handler example

​Secret rotation

Webhook Event Types

All event types

Payload structure

Event payload examples

`invoice.paid`

`invoice.email_failed`

`invoice.finalized`

`invoice.voided`

Signature verification

Node.js verification example

Express.js handler example

Secret rotation