curl https://invoice.horizonpay.co/api/v1/webhook-endpoints \
-H "Authorization: Bearer $INVOICE_AI_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/invoice-ai",
"events": ["invoice.finalized", "invoice.paid"]
}'import InvoiceAI from '@horizonpay/invoice-ai'
const invoiceai = new InvoiceAI() // reads INVOICE_AI_API_KEY
const endpoint = await invoiceai.webhookEndpoints.create({
url: 'https://example.com/webhooks/invoice-ai',
events: ['invoice.finalized', 'invoice.paid'],
})
console.log(endpoint.secret) // returned only once — store itfrom invoice_ai import InvoiceAI
client = InvoiceAI() # reads INVOICE_AI_API_KEY
endpoint = client.webhook_endpoints.create(
url="https://example.com/webhooks/invoice-ai",
events=["invoice.finalized", "invoice.paid"],
)
print(endpoint.secret) # returned only once — store it{
"data": {
"id": "4f9c2a1e-7b3d-4e8a-9c6f-2d1b0a3e5f71",
"url": "https://example.com/webhooks/invoice-ai",
"events": [
"invoice.finalized",
"invoice.paid"
],
"active": true,
"disabled_at": null,
"failure_count": 0,
"created_at": "2026-09-22T09:30:00.000Z",
"secret": "whsec_Zm9vYmFyYmF6cXV4cXV1eGNvcmdl"
}
}Create a webhook endpoint
Registers a URL to receive signed invoice events. The response carries the signing secret (whsec_…) — the only time it is returned, so store it.
URL rules: https only, at most 2048 characters, no username or password, and every address it resolves to must be public — private, loopback, link-local and IPv4-embedding IPv6 ranges (NAT64, 6to4, Teredo) are rejected. The check runs again at every delivery, and redirects are not followed.
Scope: webhooks:manage
Idempotency: Idempotency-Key optional. With one, a retry with the same key and body replays the first response (Idempotent-Replayed: true); the same key with a different body is a 422 idempotency_mismatch.
curl https://invoice.horizonpay.co/api/v1/webhook-endpoints \
-H "Authorization: Bearer $INVOICE_AI_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/invoice-ai",
"events": ["invoice.finalized", "invoice.paid"]
}'import InvoiceAI from '@horizonpay/invoice-ai'
const invoiceai = new InvoiceAI() // reads INVOICE_AI_API_KEY
const endpoint = await invoiceai.webhookEndpoints.create({
url: 'https://example.com/webhooks/invoice-ai',
events: ['invoice.finalized', 'invoice.paid'],
})
console.log(endpoint.secret) // returned only once — store itfrom invoice_ai import InvoiceAI
client = InvoiceAI() # reads INVOICE_AI_API_KEY
endpoint = client.webhook_endpoints.create(
url="https://example.com/webhooks/invoice-ai",
events=["invoice.finalized", "invoice.paid"],
)
print(endpoint.secret) # returned only once — store it{
"data": {
"id": "4f9c2a1e-7b3d-4e8a-9c6f-2d1b0a3e5f71",
"url": "https://example.com/webhooks/invoice-ai",
"events": [
"invoice.finalized",
"invoice.paid"
],
"active": true,
"disabled_at": null,
"failure_count": 0,
"created_at": "2026-09-22T09:30:00.000Z",
"secret": "whsec_Zm9vYmFyYmF6cXV4cXV1eGNvcmdl"
}
}Authorizations
An Invoice-AI API key sent as Authorization: Bearer inv_live_….
Create keys in Settings → API keys; the secret is shown once. Each key carries scopes, and every operation lists the scope it needs (x-required-scope):
business:read— Read your business profile, tax ID and bank detailsclients:read— List and read your clientsclients:write— Create, update and archive clientsproducts:read— List and read products and pricesproducts:write— Create, update and archive products and pricesinvoices:read— List and read invoices, including PDFsinvoices:write— Create, edit and delete draftsinvoices:finalize— Finalize invoices and void theminvoices:send— Email invoices to your clientspayments:write— Mark invoices as paidwebhooks:manage— Manage webhook endpoints
Keys cannot be created or revoked through the API, so a leaked key cannot mint more keys.
Headers
Body
Event types to receive. Omit or send [] to receive every type, including ones added later.
invoice.created, invoice.updated, invoice.finalized, invoice.emailed, invoice.email_failed, invoice.viewed, invoice.downloaded, invoice.paid, invoice.voided ["invoice.finalized", "invoice.paid"]