Skip to main content

Receive Events with Webhooks

Webhooks let Fiskl notify your system the moment something happens, such as an invoice being paid. Instead of repeatedly asking the API for changes, you receive a message as each event occurs. This guide explains how to set up webhook endpoints, which events are available, and what each message contains.

Before You Begin​

  • You need the integration.write permission to manage webhooks.
  • Have a public HTTPS URL ready to receive messages — the address in your system that Fiskl will send events to.

Open the Webhook Portal​

Fiskl manages webhooks through a secure portal where you add endpoints and view delivery activity.

  1. Go to Settings > API & Connections > Webhooks.
  2. Select Manage webhooks to open the portal.

The portal opens through a single-use, short-lived link. If you leave and return to the Webhooks screen, a fresh link opens automatically — this is expected.

info

The webhook portal is provided through Fiskl's delivery partner and carries their branding. The endpoints, events, and logs are all your company's own data.

Add an Endpoint​

Inside the portal you can:

  • Add an endpoint — enter your HTTPS URL and select the event types it should receive.
  • View delivery logs — see every attempt, its status code, and the response.
  • Replay a delivery — resend a failed or past event for testing.
  • Manage the signing secret — view and rotate the secret your system uses to verify messages.

Event Catalogue​

Select only the events your endpoint needs. Fiskl sends the following events:

Event typeSent when
invoice.createdAn invoice is created
invoice.updatedAn invoice is updated
invoice.deletedAn invoice is deleted
invoice.sentAn invoice is sent to the client
invoice.paidAn invoice is fully paid
invoice.partialAn invoice is partially paid
invoice.overdueAn invoice becomes overdue
invoice.rejectedAn invoice is rejected
client.createdA client is created
client.updatedA client is updated
client.deletedA client is deleted
quote.createdA quote is created
quote.updatedA quote is updated
quote.deletedA quote is deleted
payment.createdA payment is recorded
payment.deletedA payment is deleted

Message Format​

Each message is a JSON object. The data field matches the response you get from the matching GET /v1/... endpoint, so you can handle webhook data and API data the same way.

{
  "id": "msg_12345",
  "type": "invoice.paid",
  "createdAt": "2026-06-13T10:00:00Z",
  "data": {
    "id": 4821,
    "status": "Paid"
  }
}

Verify Each Message​

Every message is signed with your endpoint's signing secret. Verify the signature in your code before you act on a message, so you can be sure it came from Fiskl. You can view and rotate the signing secret in the portal.

warning

Treat the signing secret like a password. If it is exposed, rotate it in the portal and update your system.

Common Issues​

The Webhooks screen says webhooks aren't available

Webhook delivery is not enabled in every environment. If you see this message on a test environment, use production to set up live webhooks.

Messages aren't arriving at my endpoint

Open the portal and check the delivery logs for that endpoint. Confirm the URL is correct and publicly reachable over HTTPS, then replay a recent event to test. The logs show the status code your endpoint returned.