Guideinvoice webhooksend invoices to n8n, Make or Zapier

Invoice webhooks: what they are and how to send every invoice to n8n, Make or Zapier

What a webhook is, what an invoice webhook should carry, and how to connect Gennai to n8n, Make, Zapier or your own server, with a checklist for paying safely.

Nikita DegtyarevNikita DegtyarevCo-Founder11 min read
n8n workflow canvas showing a Gennai webhook node followed by a signature check and three routing paths for each invoice

A webhook is a message one system sends to a web address you control the moment something happens. Instead of you checking an app for news, the app tells you. Gennai now sends webhooks for invoices: when an invoice is created, approved, ready to pay or paid, Gennai posts the whole invoice, as JSON, to the address you choose. From there, n8n, Make, Zapier or your own server can do the next step.

This guide explains how webhooks work, what a good invoice webhook should contain, how to connect Gennai in a few minutes, and how to build the one automation where mistakes cost money: paying a supplier.

What a webhook is, in plain terms

Most software integrations work by polling. Your tool asks another tool "anything new?" every few minutes. Most of those requests come back empty, and anything that arrives between two checks waits for the next one.

A webhook reverses the direction. You give the sending app a URL once. When an event happens, the app makes an HTTP POST request to that URL with the details in the body. Make's own guide puts the difference this way: webhooks are triggered by an event, not simply the presence of new information.

Four parts make up every webhook:

  • The URL that receives the message. Your automation tool generates it.
  • The event that caused it, such as an invoice being approved.
  • The payload, the data about that event, usually JSON.
  • The signature, a value that proves the message came from the sender and was not altered.

The signature is the part people skip and later regret. A webhook URL is just a web address. Anyone who learns it can post to it. If the automation behind it moves money or updates your books, you need a way to tell a real message from a forged one.

How webhooks are signed

Gennai webhooks carry three headers: webhook-id, webhook-timestamp and webhook-signature. These are the headers of Standard Webhooks, an open specification. In that scheme (standardwebhooks.com), the signature is an HMAC-SHA256 hash computed over the webhook id, the timestamp and the body, using a secret that starts with whsec_. The receiver recomputes it with the same secret and compares.

Two details matter in practice:

  1. Use the raw body. The signature covers the exact bytes that were sent. If your tool re-serializes the JSON before you check it, the signature will not match.
  2. Check the timestamp. A common replay guard is to reject any message whose timestamp is more than a few minutes old (five is the usual tolerance).

Gennai gives you the signing secret when you set up a webhook. You can generate a new one at any time, and the old secret keeps signing for 24 hours so you can swap it without a gap.

What Gennai sends

Gennai sends four notices. Each one tells you something different about where the invoice is in its life.

NoticeWhen it is sentTypical use
invoice.createdA new invoice has been capturedLog it, alert a channel, start an intake checklist
invoice.approvedThe invoice has been approvedKick off your payment preparation
invoice.to_payThe invoice is ready to be paidBuild a payment list or a draft payment
invoice.paidThe invoice is marked as paidClose the loop in your tracker or notify the supplier

A few rules shape what you will and will not receive:

  • Only events that happen after you add the webhook are sent. Nothing is replayed from the past.
  • invoice.created is not sent for "Find past invoices" or bulk uploads, so a historical import will not flood your automation.
  • A notice is not sent if it is no longer true when it falls due, so you do not get a stale message.
  • If a workspace moves to the Free plan, webhooks pause. Anything that happens while a webhook is paused is not sent later.

Webhooks are included in every paid plan from Starter, up to five per workspace. The owner, members and accountants can manage them.

What is inside an invoice webhook

Each notice carries the whole invoice and its payment status at that moment, so your automation does not need to look anything up. This is a trimmed notice for an approved invoice:

{
  "type": "invoice.approved",
  "data": {
    "invoice": {
      "id": "cmx8k2…",
      "number": "INV-2041",
      "due_date": "2026-12-02",
      "supplier": { "name": "Example Supplies Ltd" },
      "amount": { "total": "120.00", "currency": "GBP" },
      "payment": {
        "status": "to_pay",
        "amount_due": "120.00",
        "account_number": "12345678",
        "sort_code": "12-34-56",
        "reference": "INV-2041",
        "bank_details_check": "trusted",
        "hold_reasons": ["informational_event"]
      },
      "flags": { "possible_duplicate": false },
      "erp": { "xero": { "invoice_id": "8f2c…" } },
      "pdf_url": "https://www.gennai.io/api/…"
    }
  }
}

The fields worth knowing:

  • data.invoice.id is the same in every notice for the same invoice. It is your key for "have I seen this invoice before?".
  • supplier and amount hold the supplier details, tax numbers, total, subtotal, tax and currency.
  • payment.status says where the invoice stands: to_pay, overdue, scheduled, direct_debit, partly_paid, paid, credit_note and a few others. payment.amount_due is what is left to pay.
  • Bank details are as written on the invoice: IBAN and BIC, account number and sort code, routing number, BSB, BPAY details and the supplier's own reference, depending on the country.
  • payment.bank_details_check compares those details with what Gennai has seen from the same supplier: trusted, new, changed, drift or unknown.
  • payment.hold_reasons lists reasons to wait before paying. The reason informational_event can be ignored. Any other reason means wait.
  • flags include approved, archived and possible_duplicate.
  • erp gives the matching bill or expense ids in Xero or QuickBooks, when the invoice has been exported there.
  • pdf_url points to the invoice PDF and is valid for 24 hours. Download it inside your flow if you need to keep it.

Test notices carry "test": true and never include the PDF link, so you can build safely before real invoices arrive.

Connect Gennai in four steps

The steps are the same whatever tool receives the webhook.

1. Create the receiving address. In your tool, create a webhook and copy its address:

2. Add it in Gennai. Go to Integrations, then Export & Sync, then Webhooks, and choose Connect (or Manage), then Add webhook. Paste the address and optionally name it. Tick the notices you want. None are ticked by default. Tick the consent box, save and turn the webhook on.

3. Copy the signing secret. You will paste it into the step that checks the signature.

4. Send a test. Gennai sends a full notice marked "test": true. Check that it arrives and that your signature check passes before you do anything else.

There is an optional extra under Advanced options: an authentication header that Gennai sends on top of the signature, for receivers that require one.

Start from the ready-made n8n flow

If you use n8n, you do not have to build the checks yourself. Gennai provides a template. In n8n choose Import > From URL and paste https://www.gennai.io/help/files/gennai-n8n-template.json.

Then:

  1. Copy the Production URL of the webhook node into Gennai.
  2. Paste the signing secret into the node called "Check it comes from Gennai".
  3. Publish the workflow. On older n8n versions, set it to Active.
  4. Send a test from Gennai.

The flow verifies the signature, downloads the PDF when there is one, and sorts every invoice into one of three paths:

  • Your step goes here: approved, still to pay or overdue, and nothing to check. This is where you add your own action.
  • Check by hand first: new or changed bank details, a possible duplicate, partly paid, missing data or already sent. The reason travels with the invoice.
  • Nothing to pay: tests, and invoices that are already paid, paid by card or direct debit, or credit notes.

The template pays nothing by itself. You add the step, such as a draft payment in your bank or payment app. If you self-host n8n, the Code node must be allowed to use the crypto module. n8n Cloud already allows it.

The rules for automating payments from an invoice webhook

Any webhook that can lead to a payment needs rules that are stricter than the rules for logging or notifying. Gennai does not make payments and does not move money. Your automation does, so the discipline lives in your flow. These are the checks that matter, and they map directly to fields in the notice.

Pay only when all three are true:

  • payment.status is to_pay or overdue.
  • payment.bank_details_check is trusted.
  • payment.hold_reasons contains nothing except informational_event.

And always:

  1. Verify the signature first. Never act on a notice you have not verified. This is the only thing standing between a forged request and a payment.
  2. Pay each invoice once. Keep a list of the data.invoice.id values you have already paid. Re-approving an invoice sends a new Approved notice with a new webhook-id, so deduplicating on the delivery id alone is not enough. The invoice id is the safer key.
  3. Keep the supplier's reference on the payment. Use the reference from the notice so the supplier can match the money to the invoice.
  4. Stop on changed bank details. When bank_details_check is new, changed or drift, do not pay automatically. Confirm the details with the supplier by phone, using a number you already had, before releasing money. A changed bank account is one of the classic patterns in supplier invoice fraud.
  5. Hold anything flagged. possible_duplicate: true (see how duplicate invoices slip through), partly_paid and missing data belong in a human review queue.

None of this requires heavy tooling. It is a short chain of conditions, and the n8n template already implements the sorting. What you add is the last step and the memory of what you have paid.

Keeping the connection reliable

Webhooks are delivered over the internet, so receivers should expect retries, duplicates and the occasional outage.

  • Respond quickly with a 2xx status. Gennai expects an answer within 15 seconds. Do slow work after you have acknowledged the message.
  • Expect retries. If delivery fails, Gennai retries for up to three days, and every retry keeps the same webhook-id. That id is how you spot a repeat.
  • Rate limits are respected. If your receiver answers 429 or 503 with a Retry-After header, Gennai waits.
  • Redirects are not followed. Use the final address.
  • A webhook can stop. An HTTP 410 response, or three days of failures, moves it to Stopped, and events while it is stopped are not sent. Fix the receiver, then use "Turn on again".
  • You can see what happened. Recent deliveries from the last 30 days are visible in Gennai.

If something is wrong, start here:

SymptomLikely cause
404 on the testThe n8n workflow is not published, or the Zap is off
401 or 403The authentication header does not match
Signature mismatchThe tool changed the body (use the raw body; in n8n choose Raw Body), the wrong secret is in use, or the server clock is off

What to build with it

For the wider picture of connecting invoice tools to your books, see the invoice system integration guide. Here, the focus is what you can build on top of the webhook.

Once invoices arrive as structured data, the useful automations are modest and specific:

  • Post each approved invoice to a team channel with supplier, amount and due date.
  • Append every invoice to a sheet your client or partner already reads, with the PDF downloaded and stored.
  • Route invoices with changed bank details to a named reviewer, with the reason attached.
  • Prepare a payment run from invoices that pass the checks above, for a person to approve in the bank.
  • Mark an invoice as settled in your project or CRM tool when invoice.paid arrives.

For accountants and bookkeepers managing several clients, the same webhook structure repeats per workspace, so one reviewed flow can be copied instead of rebuilt.

Privacy and where the data goes

Gennai sends invoice data only to the addresses you add. Under Gennai's terms, that data cannot be used for advertising, sold, used for credit decisions or used to train AI. You stay in control of the destination, and you can pause or remove a webhook at any time.

Frequently asked questions

Do I need to write code? No. If you are still choosing between tools, Zapier vs Make for invoice automation compares them. n8n, Make and Zapier each give you a URL without code, and Gennai's n8n template covers the signature check and routing. Your own server needs code to receive and verify the request.

Why did I not receive my old invoices? Webhooks send events that happen after you add them. They are not a backfill. Gennai also does not send invoice.created for "Find past invoices" or bulk uploads.

Is a webhook the same as an API? No. An API answers when you ask. A webhook speaks when something happens. Gennai webhooks push notices to you so you do not need to keep checking.

Can I use more than one? Yes, up to five per workspace. For example, one for your accounting team's channel and one for your payment preparation flow.

Where to start

Add a webhook, tick only invoice.approved, import the n8n template and send a test. You will see a full invoice arrive, signed and sorted, in a few minutes. Then add your own step at the end.

If you are not using Gennai yet, you can start free and connect your inbox to see how invoices arrive, and the full webhook guide covers every field and setting.

invoice webhooksend invoices to n8n, Make or Zapier