Webhooks: send invoices to n8n, Make or Zapier

Get a notice in n8n, Make, Zapier or your own server when an invoice arrives, is approved, goes into To pay or is paid, with its data and its PDF.

From StarterLast verified

Gennai can tell your other tools when something happens to an invoice. When an invoice arrives, is approved, goes into To pay or is paid, Gennai sends its data to an address you choose: the supplier, the amounts, the due date, the bank details and a link to the PDF. Your flow in n8n, Make or Zapier, or your own server, takes it from there. For example, it can prepare a payment, add a row to a spreadsheet or tell your team.

Webhooks are included in every paid plan, from Starter.

In this guide:

How it works

  1. In n8n, Make or Zapier, you create a webhook: an address that waits for messages.
  2. In Gennai, you paste that address and choose which notices you want.
  3. Each time one of those things happens to an invoice, Gennai sends the invoice's data to that address, and your flow runs.

Gennai sends what happens from the moment you add the webhook. Nothing from before is sent.

The notices

NoticeWhen Gennai sends it
New invoiceWhen a new invoice comes in. Not sent for invoices you bring in with Find past invoices or a bulk upload.
ApprovedWhen someone on your team approves an invoice.
To payWhen a new invoice lands in To pay.
PaidWhen an invoice is paid.

Each notice carries the whole invoice and its payment status at that moment. If something is no longer true when a notice is due to go out, for example an approved invoice that someone un-approved, Gennai doesn't send it.

To pay invoices from your flow, start from Approved: it means someone on your team has checked the invoice. Pay it only if its status is to_pay or overdue, payment.bank_details_check is trusted and payment.hold_reasons has nothing but informational_event. Keep the supplier's own reference on the payment. And pay each invoice once: if someone approves it again, Gennai sends a new Approved, with a new webhook-id. Keep a list of the data.invoice.id of the invoices you pay, in a spreadsheet, a database or your payment app, and skip any that's already on it. The n8n template below does the other checks for you.

Add a webhook

  1. In Gennai, open Integrations.
  2. Under Export & Sync, find Webhooks and click Connect. If you already have a webhook, the button says Manage.
  3. Click Add webhook.
  4. In Address (URL), paste the address from n8n, Make or Zapier. It must start with https://.
  5. Optionally, give it a Name, so you can spot it in the list.
  6. Under Which notices do you want, tick the ones you'll use. None are ticked to start with.
  7. Tick the box to agree to Gennai sending the invoices' data to that address, and click Save and turn on.

The webhook opens with its Signing secret. Click Copy and keep it somewhere safe: you'll use it to check that each notice really comes from Gennai.

  • Each workspace can have up to 5 webhooks.
  • The owner, members and accountants can add and manage webhooks. See Roles and permissions.
  • If your receiver asks for a key in a header, for example n8n's Header Auth or Power Automate, add it in Advanced options › Authentication header. Gennai sends it with every notice, on top of the signature.

Send a test

  1. Open the webhook and find Test.
  2. In the list next to Send test, choose the notice to try, such as Approved or Paid, and click Send test.
  3. Gennai shows straight away whether your receiver got it, or what went wrong.

A test sends a sample invoice in the state of the notice you chose: a Paid test arrives as paid and a To pay test as to pay. Tests carry "test": true and never include a PDF link. Use them to build your flow. Real notices start as soon as something happens to one of your invoices.

Use the n8n template

The template is a ready-made n8n workflow. It checks that each notice comes from Gennai, sorts the invoices you need to pay from the rest and downloads the PDF.

  1. In n8n, create a new workflow.

  2. Open the ... menu at the top right, choose Import › From URL (in older versions, Import from URL...) and paste: https://www.gennai.io/help/files/gennai-n8n-template.json. You can also open that link, copy everything and paste it onto the n8n canvas.

  3. Open the Gennai webhook node and copy its Production URL.

  4. In Gennai, add a webhook with that address, as in Add a webhook, and copy its signing secret.

  5. In n8n, open the Check it comes from Gennai node and paste the secret between the quotes on the first line.

  6. Publish the workflow. In older versions of n8n, switch it to Active instead.

    If you host n8n yourself, first allow the crypto module in the Code node, as explained in n8n's guide. n8n Cloud allows it already.

  7. In Gennai, click Send test. In n8n, open Executions: you should see the test, checked.

What the template does with each notice:

  • Checks the signature. A notice that doesn't come from Gennai stops there.
  • Downloads the PDF, when the notice has one.
  • Finds the invoices to pay: approved, not paid yet, and never a test.
  • Sends to your payment step only the invoices Gennai sees as safe to pay, and skips the ones it remembers sending there. The rest goes to Check by hand first, with the reason.

The template doesn't pay anything by itself. Add your own step where it says Your payment step goes here, for example to prepare a transfer in your bank or payment app, and check your list of invoices already paid there first.

Build your own flow

In n8n, with a Webhook node:

  • Set HTTP Method to POST.
  • Copy the Production URL and publish the workflow. The production address only answers while the workflow is published; if it isn't, the test in Gennai says 404. While you build, you can use the Test URL and click Listen for test event before each test.
  • Set Respond to Immediately, so Gennai gets its answer at once.
  • To check the signature, turn on Raw Body in the node's options. The template's code does the check; you can copy it from the Check it comes from Gennai node.

In Make, start a scenario with Webhooks › Custom webhook, copy its address and paste it in Gennai. Send a test so Make learns the shape of the data.

In Zapier, start a Zap with Webhooks by Zapier › Catch Hook, copy its address and paste it in Gennai. Send a test, and turn the Zap on.

In Google Apps Script, for example to add each invoice to a Google Sheet:

  • Write a doPost(e) function. The notice is in e.postData.contents: read it with JSON.parse, and end with return ContentService.createTextOutput('ok').
  • Click Deploy › New deployment, choose Web app and set Who has access to Anyone. Paste the Web app URL, the one that ends in /exec, in Gennai.
  • Once your script has run, Google answers with a redirect. Gennai counts it as received, so the test says Received · answered 302.
  • When you change the script, deploy it again: in Deploy › Manage deployments, edit the deployment and choose New version. The address keeps running the version you deployed.
  • Apps Script doesn't pass the headers to your script, so you can't check the signature there. Share the web app's address only with people you trust.
  • A notice can arrive more than once. To ignore repeats, keep the type, timestamp and data.invoice.id of the notices you've handled.
  • If your script fails, Google still answers as if all went well, so Gennai doesn't send the notice again. Check Executions in Apps Script now and then.

On your own server, accept a POST with a JSON body and answer with a 2xx code. Check the signature before you do anything with the notice.

Check that a notice comes from Gennai

Every notice is signed with your webhook's signing secret, following the open Standard Webhooks specification. Check the signature before you act on a notice, and always before you pay anything.

Each notice comes with three headers:

  • webhook-id: the notice's id. It stays the same if Gennai sends the notice again, so you can ignore repeats.
  • webhook-timestamp: when this attempt was sent, in seconds.
  • webhook-signature: v1, followed by the signature. After you generate a new secret, there are two for 24 hours, separated by a space: accept the notice if either one matches.

To check a notice:

  1. Take your signing secret, remove whsec_ from the start and decode the rest from base64. That's your key.
  2. Join webhook-id, webhook-timestamp and the body exactly as it arrived, before you parse it, with a dot between each.
  3. Calculate the HMAC-SHA256 of that text with your key and encode the result in base64.
  4. Compare it with the signatures in webhook-signature, after v1,. If one matches and the timestamp is less than 5 minutes old, the notice comes from Gennai.

The Standard Webhooks libraries do this for you in most programming languages.

If your tool can't check signatures, add an authentication header in Advanced options, check it in your flow and keep the webhook's address private.

What a notice contains

A notice is a JSON body with the notice's type, its timestamp and the invoice under data.invoice. Send a test to see a full one. These are the fields you'll use most:

  • type: the notice. invoice.created, invoice.approved, invoice.to_pay or invoice.paid.
  • timestamp: when it happened, in UTC.
  • test: true on tests. Real notices don't have it.
  • data.invoice.id: the invoice's id in Gennai. It's the same in every notice about that invoice.
  • number, invoice_date and due_date: from the document. Dates are written as YYYY-MM-DD.
  • supplier: the supplier's name, address, tax numbers and country.
  • amount: total, subtotal and tax as text, such as "120.00", and the currency code. The currency is empty if the invoice doesn't say it.
  • payment.status: where the invoice stands. See below.
  • payment.amount_due: what's left to pay. Empty when there's nothing to pay, or when the invoice itself shows that part of it was already paid.
  • The bank details in payment: iban, bic, account_number, sort_code, routing_number, bsb, bpay_biller_code, bpay_reference and reference, as they appear on the invoice. The ones it doesn't have are empty. For BPAY, the customer reference is bpay_reference, or reference when that's empty.
  • payment.bank_details_check: whether these are the bank details you usually pay this supplier. See below.
  • payment.hold_reasons: the reasons Gennai would wait before paying this invoice, for example new bank details, a possible duplicate, or an invoice that says part of it is already paid. informational_event only says the notice is for information: ignore it. Any other reason means wait.
  • payment.paid_at and payment.paid_evidence: when it was paid, and how Gennai knows. confirmed when someone marked it as paid or it matched your bank statement, assumed when Gennai takes it as paid, for example after a payment file, a direct debit or a card purchase. paid_at can be empty when it's assumed.
  • flags: approved, archived and possible_duplicate.
  • erp: the bill's ids in Xero or QuickBooks, if Gennai sent it there. If it went to QuickBooks as an expense, bill_id is empty and expense_id has the expense's id.
  • pdf_url: a link to download the PDF. It works for 24 hours, so download the file when the notice arrives. Empty in tests and when the invoice has no PDF.

payment.status is the same status you see in Gennai:

  • to_pay (To pay): not paid yet.
  • overdue (Overdue): not paid and past its due date.
  • scheduled (Scheduled): not paid yet, and a payment is already scheduled.
  • direct_debit (Direct debit): the supplier collects it by direct debit.
  • partly_paid (Partly paid): part of it is paid. amount_due says what's left.
  • paid (Paid): paid.
  • history_assumed_paid (History, assumed paid): it was already past its due date when it reached Gennai, so Gennai assumes it's paid.
  • credit_note (Credit note): a credit note. There's nothing to pay.
  • self_issued (Issued by you): an invoice your business issued, not a bill to pay.
  • archived (Archived): someone archived it without paying it. Don't pay it.
  • non_accounting (Non-accounting): it isn't an accounting document.
  • unclassified (Unclassified): it doesn't have a payment status yet.

payment.bank_details_check tells you whether to trust the bank details:

  • trusted: the bank details you've paid this supplier most often, counting the invoices someone marked as paid in Gennai or that Gennai matched with your bank statement.
  • new: you haven't paid this supplier to these bank details yet.
  • changed: different from the bank details you usually pay this supplier.
  • drift: almost the same as usual, with a small difference. Often a number read wrong.
  • unknown: the invoice has no bank details Gennai can check.

With new, changed or drift, confirm the bank details with the supplier, by phone, before you pay.

If your receiver doesn't answer

  • Answer with a 2xx code within 15 seconds. If your flow takes longer, answer first and do the work afterwards. In n8n, that's Respond › Immediately.
  • If your receiver doesn't answer, or answers with an error, Gennai sends the notice again, for up to 3 days. The webhook-id stays the same, so you can ignore repeats.
  • If your receiver answers 429 or 503 with a Retry-After header, Gennai waits before it tries again.
  • If every delivery fails for 3 days in a row, or your receiver answers 410, Gennai stops the webhook and shows it as Stopped. Fix your receiver and click Turn on again. What happened while it was stopped isn't sent.
  • Gennai doesn't follow redirects. Paste the final address. Google Apps Script is the exception: see Build your own flow.

Open a webhook to see its Recent deliveries from the last 30 days: when each notice went out, for which invoice and how it went.

Pause, change or delete a webhook

Open Integrations › Webhooks › Manage and click the webhook.

  • Under Status, switch it between Active and Paused. While it's paused nothing is sent, and what happens in that time isn't sent later.
  • Edit changes the address, the name or the notices.
  • Generate new secret replaces the signing secret. The current one keeps signing for 24 more hours, so you have time to update your flow. Do it straight away if you think someone else has your secret.
  • Delete webhook stops it for good.

If your workspace moves to the Free plan, its webhooks pause. Any paid plan turns them back on. What happens in between isn't sent.

Gennai sends the invoices' data only to the addresses you add. Under our terms, that data can't be used for advertising, sold to third parties, used for credit decisions or used to train AI. See our Privacy Policy.

Troubleshooting

The test says 404

Your receiver doesn't recognise the address. In n8n, publish the workflow, or use the Test URL and click Listen for test event first. In Zapier, turn the Zap on.

The test says your receiver refused it

Your receiver answered 401 or 403. Check the authentication header in Advanced options, and that it matches what your receiver expects.

No answer within 15 seconds

Make your receiver answer first and do the work afterwards. In n8n, set Respond to Immediately.

The signature doesn't match

  • Use the body exactly as it arrived, before you parse it. In n8n, turn on Raw Body in the Webhook node's options.
  • Copy the signing secret again, with whsec_ at the start.
  • If you generated a new secret, update it in your flow.
  • Check your server's clock: notices older than 5 minutes are refused.

The template says the crypto module is disallowed

n8n says Module 'crypto' is disallowed (in older versions, Cannot find module 'crypto') when it's hosted by you or your company and that module isn't allowed yet. Ask whoever runs it to allow the crypto module in the Code node, as explained in n8n's guide. n8n Cloud allows it already.

The webhook shows Stopped

Every delivery failed for 3 days in a row, or your receiver said the address no longer exists. Check that your flow is on and its address hasn't changed, send a test, and click Turn on again.