Webhooks

Webhooks push events to your own systems the moment something happens in your account: an invoice is sent or paid, a client submits a payment proof, an estimate is accepted. You add an HTTPS URL, choose the events you care about, and we POST a signed JSON event to it every time one of them happens. This page shows how to set up and manage endpoints. The payload, signature scheme and full event list are in Webhook events.

Webhooks are available on every plan from launch.

Before you start

• You need the integrations.manage permission. Owners and Admins have it by default.
• You need a public HTTPS URL that can receive POST requests. Plain http, private network addresses and internal hostnames are refused (proposed: port 443 only, and redirects are not followed).
• Your endpoint should verify the signature on every request. The Node.js sample does it in a few lines.

Add an endpoint in the app

Add an endpoint through the API

Use Create or update a webhook endpoint. The same call updates an endpoint when you pass its id; PATCH /v1/webhook-endpoints/{id} also works.

curl -X POST "https://api.freeinvoiceautomation.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $FIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-endpoint-billing-server" \
  -d '{
    "url": "https://example.com/webhooks/fia",
    "events": ["document.sent", "document.paid", "payment.succeeded", "credit_note.created"],
    "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f"
  }'

The endpoint fields are:

The signing secret is write-only after creation: no later response contains it, only its last four characters.

Manage endpoints

All of them need integrations.manage.

Test your endpoint

The test sends a sample signed event to your URL, so you can check three things before real events arrive:

1. Your server is reachable over HTTPS from the internet.
2. Your signature check accepts our signature with your secret.
3. You return a 2xx status quickly.

curl -X POST "https://api.freeinvoiceautomation.com/v1/webhook-endpoints/0193f3b0-2c3d-7e4f-8a9b-0c1d2e3f4a5b/test" \
  -H "Authorization: Bearer $FIA_API_KEY" \
  -H "Idempotency-Key: webhook-test-1"

The delivery log

Every delivery is recorded per endpoint, with its event id, event type, status, number of attempts, the last HTTP status your server returned, the next attempt time and when it was delivered.

Failed deliveries are retried with exponential backoff, about 8 attempts over roughly 24 hours (proposed). The event keeps the same id on every retry, so your endpoint can ignore repeats.

Redeliver an event

After you fix a problem on your side, send dead or failed deliveries again from the delivery log, or with Redeliver a webhook:

curl -X POST "https://api.freeinvoiceautomation.com/v1/webhook-deliveries/0193f3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b/redeliver" \
  -H "Authorization: Bearer $FIA_API_KEY" \
  -H "Idempotency-Key: redeliver-0193f3c4"

A redelivered event has the same id as the original, so if you already processed it, your deduplication skips it safely.

Endpoints that keep failing

An endpoint whose deliveries fail again and again can be disabled automatically (proposed: after 50 failed deliveries in a row). Its status becomes disabled and nothing more is sent until you fix the problem and set it back to active. Events that happened while it was disabled can be caught up through the API using the list endpoints with updated_after. See Pagination and filters.

Rotate the signing secret

If a secret may have leaked, rotate it. For a grace period we sign each delivery with both the old and the new secret, so your server keeps accepting deliveries while you deploy the new one. See Rotating the secret.

Writing a reliable receiver

Common uses

Related pages