cURL

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 it

from 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"
  }
}

Webhook endpoints

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.

POST

/

webhook-endpoints

cURL

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 it

from 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

Authorization

string

header

required

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 details
clients:read — List and read your clients
clients:write — Create, update and archive clients
products:read — List and read products and prices
products:write — Create, update and archive products and prices
invoices:read — List and read invoices, including PDFs
invoices:write — Create, edit and delete drafts
invoices:finalize — Finalize invoices and void them
invoices:send — Email invoices to your clients
payments:write — Mark invoices as paid
webhooks:manage — Manage webhook endpoints

Keys cannot be created or revoked through the API, so a leaked key cannot mint more keys.

Headers

Idempotency-Key

string

A unique key per distinct operation (a UUID works), reused only when retrying that same request. Up to 255 characters; stored for 24 hours.

Maximum string length: 255

Example:

"6f1c2d9e-8a4b-4c3f-9e7d-2b5a1c8f4e30"

Body

application/json

url

string

required

An https:// URL of up to 2048 characters, without a username or password, that resolves only to public addresses. Redirects are not followed.

Example:

"https://example.com/webhooks/invoice-ai"

events

enum<string>[]

Event types to receive. Omit or send [] to receive every type, including ones added later.

Available options:

invoice.created,

invoice.updated,

invoice.finalized,

invoice.emailed,

invoice.email_failed,

invoice.viewed,

invoice.downloaded,

invoice.paid,

invoice.voided

Example:

["invoice.finalized", "invoice.paid"]

Response

The endpoint, with its signing secret.

data

object

required

The created endpoint, including its secret.

Show child attributes