Webhook Events

faktoora sends HTTP POST requests to your registered endpoint when document events occur. The action value identifies the event and is the same value used to subscribe.

Action	Trigger
`invoiceCreate`	Outgoing invoice created
`invoiceSent`	Outgoing invoice sent via email
`invoiceOverdue`	Invoice marked overdue by the daily cron
`invoiceIncomingCreate`	Incoming invoice created or validated
`invoiceIncomingSent`	Incoming invoice forwarded via email
`offerCreate`	Quotation (offer) created
`offerSent`	Offer sent via email
`letterCreate`	Letter document created
`letterSent`	Letter sent via email
`reminderCreate`	Reminder (dunning notice) created
`reminderSent`	Reminder sent via email
`orderConfirmationCreate`	Order confirmation created
`orderConfirmationSent`	Order confirmation sent via email
`customerCreate`	Customer created
`productCreate`	Product created
`validationJobCompleted`	E-invoice validation job finished

Managing Webhooks

All webhook management endpoints require apiKeyAuth.

Endpoint	Method	Description
GET `/webhooks`	GET	List all registered webhook subscriptions.
POST `/webhooks`	POST	Register a new webhook subscription.
PATCH `/webhooks/{id}`	PATCH	Update an existing webhook subscription. `{id}` is a UUID.
DELETE `/webhooks/{id}`	DELETE	Remove a webhook subscription. Returns `{ "succeed": true }`.

The action field accepts any value from the event table above.

Target URL requirements

The target URL must resolve to a publicly reachable address. The API performs a DNS-resolution check at registration time and rejects targets that resolve to:

Loopback addresses (e.g. http://localhost/..., http://127.0.0.1/...)
RFC 1918 private ranges (e.g. http://192.168.x.x/..., http://10.x.x.x/..., http://172.16-31.x.x/...)
Unresolvable / reserved TLDs (.invalid, .local, etc.)
Other blocked / internal IPs

A rejected target returns:

{ "code": "BAD_REQUEST", "statusCode": 400, "message": "URL resolves to blocked/internal IP" }

If you host your endpoint behind internal DNS, expose it via a public proxy before subscribing.

Example: Register a webhook

curl -X POST \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "invoiceCreate",
    "target": "https://your-endpoint.example.com/hook"
  }' \
  https://api.faktoora.com/api/v1/webhooks

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "action": "invoiceCreate",
  "target": "https://your-endpoint.example.com/hook",
  "createdAt": "2026-05-26T13:55:02.970Z",
  "updatedAt": "2026-05-26T13:55:02.970Z"
}

The id field is a UUID. Use it in PATCH and DELETE requests.

Example: Update a webhook

curl -X PATCH \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "invoiceCreate",
    "target": "https://new-endpoint.example.com/hook"
  }' \
  https://api.faktoora.com/api/v1/webhooks/550e8400-e29b-41d4-a716-446655440000

Example: Delete a webhook

curl -X DELETE \
  -H "X-API-KEY: your-api-token" \
  https://api.faktoora.com/api/v1/webhooks/550e8400-e29b-41d4-a716-446655440000

Response (200 OK)

{ "succeed": true }

Event Details

invoiceCreate

{
  "faktooraId": "<string>",
  "action": "invoiceCreate",
  "payload": {
    "faktooraId": "<string>",
    "amount": "<number>",
    "outstandingBalance": "<number>",
    "currency": "<string>",
    "invoiceNumber": "<string>",
    "invoiceTypeCode": "<number>",
    "status": "<string>",
    "format": "<string>",
    "issueDate": "<string>",
    "dueDate": "<string>",
    "deliveryDate": "<string>",
    "orderNumber": "<string>",
    "shippingOrderNumber": "<string>",
    "contractNumber": "<string>",
    "assignmentNumber": "<string>",
    "orderReferenceId": "<string>",
    "buyerReferenceId": "<string>",
    "mandateReference": "<string>",
    "projectName": "<string>",
    "totalCosts": "<number>",
    "createdAt": "<string>",
    "detailsPage": "<string>"
  }
}

invoiceOverdue

{
  "trigger": {
    "outputFields": {
      "invoice": { /* full invoice object */ },
      "detailsPage": "<string>"
    }
  }
}

invoiceSent

{
  "action": "invoiceSent",
  "faktooraId": "<string>",
  "payload": {
    "id": "<invoiceId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

invoiceIncomingCreate

{
  "action": "invoiceIncomingCreate",
  "payload": {
    "id": "<invoiceIncomingId>",
    "importId": "<string>",
    "amount": "<number>",
    "taxAmount": "<number>",
    "outstandingBalance": "<number>",
    "invoiceCurrencyCode": "<string>",
    "invoiceNumber": "<string>",
    "issueDate": "<string>",
    "dueDate": "<string>",
    "paymentDate": "<string>",
    "sellerName": "<string>",
    "type": "<string>",
    "inputType": "<string>",
    "buyerReference": "<string>",
    "isValid": "<boolean>",
    "createdAt": "<string>",
    "detailsPage": "<string>"
  }
}

invoiceIncomingSent

{
  "action": "invoiceIncomingSent",
  "payload": {
    "id": "<invoiceIncomingId>",
    "detailsPage": "<string>"
  }
}

offerCreate

{
  "action": "offerCreate",
  "faktooraId": "<string>",
  "payload": {
    "id": "<offerId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

offerSent

{
  "action": "offerSent",
  "faktooraId": "<string>",
  "payload": {
    "id": "<offerId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

letterCreate

{
  "action": "letterCreate",
  "faktooraId": "<string>",
  "payload": {
    "id": "<letterId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

letterSent

{
  "action": "letterSent",
  "faktooraId": "<string>",
  "payload": {
    "id": "<letterId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

reminderCreate

{
  "action": "reminderCreate",
  "faktooraId": "<string>",
  "payload": {
    "id": "<reminderId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

reminderSent

{
  "action": "reminderSent",
  "faktooraId": "<string>",
  "payload": {
    "id": "<reminderId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

orderConfirmationCreate

{
  "action": "orderConfirmationCreate",
  "faktooraId": "<string>",
  "payload": {
    "id": "<orderConfirmationId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

orderConfirmationSent

{
  "action": "orderConfirmationSent",
  "faktooraId": "<string>",
  "payload": {
    "id": "<orderConfirmationId>",
    "faktooraId": "<string>",
    "detailsPage": "<string>"
  }
}

customerCreate

{
  "action": "customerCreate",
  "faktooraId": "<string>",
  "payload": {
    "id": "<customerId>",
    "faktooraId": "<string>"
  }
}

productCreate

{
  "action": "productCreate",
  "payload": {
    "id": "<productId>"
  }
}

Event Flow Diagram

A high-level sequence for outgoing invoice events:

Managing Webhooks​

Target URL requirements​

Event Details​

invoiceCreate​

invoiceOverdue​

invoiceSent​

invoiceIncomingCreate​

invoiceIncomingSent​

offerCreate​

offerSent​

letterCreate​

letterSent​

reminderCreate​

reminderSent​

orderConfirmationCreate​

orderConfirmationSent​

customerCreate​

productCreate​

Event Flow Diagram​