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.
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
- The notices
- Add a webhook
- Send a test
- Use the n8n template
- Build your own flow
- Check that a notice comes from Gennai
- What a notice contains
- If your receiver doesn't answer
- Pause, change or delete a webhook
- Troubleshooting
How it works
- In n8n, Make or Zapier, you create a webhook: an address that waits for messages.
- In Gennai, you paste that address and choose which notices you want.
- 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
| Notice | When Gennai sends it |
|---|---|
| New invoice | When a new invoice comes in. Not sent for invoices you bring in with Find past invoices or a bulk upload. |
| Approved | When someone on your team approves an invoice. |
| To pay | When a new invoice lands in To pay. |
| Paid | When 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
- In Gennai, open
Integrations. - Under
Export & Sync, findWebhooksand clickConnect. If you already have a webhook, the button saysManage. - Click
Add webhook. - In
Address (URL), paste the address from n8n, Make or Zapier. It must start with https://. - Optionally, give it a
Name, so you can spot it in the list. - Under
Which notices do you want, tick the ones you'll use. None are ticked to start with. - 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
- Open the webhook and find
Test. - In the list next to
Send test, choose the notice to try, such asApprovedorPaid, and clickSend test. - 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.
-
In n8n, create a new workflow.
-
Open the
...menu at the top right, chooseImport›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. -
Open the
Gennai webhooknode and copy itsProduction URL. -
In Gennai, add a webhook with that address, as in Add a webhook, and copy its signing secret.
-
In n8n, open the
Check it comes from Gennainode and paste the secret between the quotes on the first line. -
Publish the workflow. In older versions of n8n, switch it to
Activeinstead.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.
-
In Gennai, click
Send test. In n8n, openExecutions: 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 MethodtoPOST. - Copy the
Production URLand 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 theTest URLand clickListen for test eventbefore each test. - Set
RespondtoImmediately, so Gennai gets its answer at once. - To check the signature, turn on
Raw Bodyin the node's options. The template's code does the check; you can copy it from theCheck it comes from Gennainode.
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 ine.postData.contents: read it withJSON.parse, and end withreturn ContentService.createTextOutput('ok'). - Click
Deploy›New deployment, chooseWeb appand setWho has accesstoAnyone. Paste theWeb 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 chooseNew 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,timestampanddata.invoice.idof 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
Executionsin 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:
- Take your signing secret, remove
whsec_from the start and decode the rest from base64. That's your key. - Join
webhook-id,webhook-timestampand the body exactly as it arrived, before you parse it, with a dot between each. - Calculate the HMAC-SHA256 of that text with your key and encode the result in base64.
- Compare it with the signatures in
webhook-signature, afterv1,. 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_payorinvoice.paid.timestamp: when it happened, in UTC.test:trueon 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_dateanddue_date: from the document. Dates are written as YYYY-MM-DD.supplier: the supplier's name, address, tax numbers and country.amount:total,subtotalandtaxas text, such as "120.00", and thecurrencycode. 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_referenceandreference, as they appear on the invoice. The ones it doesn't have are empty. For BPAY, the customer reference isbpay_reference, orreferencewhen 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_eventonly says the notice is for information: ignore it. Any other reason means wait.payment.paid_atandpayment.paid_evidence: when it was paid, and how Gennai knows.confirmedwhen someone marked it as paid or it matched your bank statement,assumedwhen Gennai takes it as paid, for example after a payment file, a direct debit or a card purchase.paid_atcan be empty when it's assumed.flags:approved,archivedandpossible_duplicate.erp: the bill's ids in Xero or QuickBooks, if Gennai sent it there. If it went to QuickBooks as an expense,bill_idis empty andexpense_idhas 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_duesays 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-idstays the same, so you can ignore repeats. - If your receiver answers 429 or 503 with a
Retry-Afterheader, 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 clickTurn 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 betweenActiveandPaused. While it's paused nothing is sent, and what happens in that time isn't sent later. Editchanges the address, the name or the notices.Generate new secretreplaces 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 webhookstops 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 Bodyin theWebhooknode'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.