Webhooks

A webhook endpoint is a URL on your own server that Bilify calls when something happens in your workspace, for example when an invoice is issued or a contract is signed. Your system reacts immediately instead of asking the API every few minutes.

Endpoints are managed in Settings > Integrations, section Webhooks. Owners and admins can add and change them.

Add an endpoint#

Endpoints lists the URLs that receive events from this workspace, with their environment and status.

Add endpoint opens the form.

Enter a public https URL on your own server. Private and localhost addresses are rejected.

Tick the events you want, or All events to receive everything.

Here we also subscribe to fully signed contracts.

An optional description helps you tell endpoints apart.

Save adds the endpoint and creates its signing secret.

Copy the signing secret now. Your server uses it to verify the X-Bilify-Signature header.

Done closes the window. Deliveries will show under Recent deliveries.

Next

Done

That is everything. You can replay it any time.

Start over

1. Endpoints lists the URLs that receive events from this workspace, with their environment and status.

2. Add endpoint opens the form.

3. Enter a public https URL on your own server. Private and localhost addresses are rejected.

4. Tick the events you want, or All events to receive everything.

5. Here we also subscribe to fully signed contracts.

6. An optional description helps you tell endpoints apart.

7. Save adds the endpoint and creates its signing secret.

8. Copy the signing secret now. Your server uses it to verify the X-Bilify-Signature header.

9. Done closes the window. Deliveries will show under Recent deliveries.

1. Step 1: Endpoints lists the URLs that receive events from this workspace, with their environment and status.
2. Step 2: Add endpoint opens the form.
3. Step 3: Enter a public https URL on your own server. Private and localhost addresses are rejected.
4. Step 4: Tick the events you want, or All events to receive everything.
5. Step 5: Here we also subscribe to fully signed contracts.
6. Step 6: An optional description helps you tell endpoints apart.
7. Step 7: Save adds the endpoint and creates its signing secret.
8. Step 8: Copy the signing secret now. Your server uses it to verify the X-Bilify-Signature header.
9. Step 9: Done closes the window. Deliveries will show under Recent deliveries.

1. Open Settings > Integrations and scroll to Webhooks.
2. In the Endpoints card, click Add endpoint.
3. Enter the Endpoint URL. It must be a public https:// address. Private, localhost and reserved addresses are rejected.
4. Under Events, tick the events you want, or tick All events to receive everything, including events added in the future.
5. Optionally add a Description, for example "Accounting sync".
6. Leave Active on and click Save.
7. Copy the Signing secret (it starts with whsec_) and store it with your receiver's configuration, then click Done. You need it to verify signatures.

The Environment in the form is not a choice. Endpoints you add in your production workspace receive production events only. To receive sandbox events, open the sandbox and add the endpoint there (see Sandbox mode).

Events#

Events fire no matter where the change was made: in the app, through the REST API, by the AI connector or by a scheduled job. The e-Faktura events only occur for Macedonian workspaces that use e-Faktura.

What a delivery looks like#

Bilify sends a POST with a JSON body and these headers:

Content-Type: application/json
User-Agent: Bilify-Webhooks/1
X-Bilify-Signature: t=1791100800,v1=5f2c...

{
  "event": "document.issued",
  "occurred_at": "2026-10-04T09:15:02+02:00",
  "environment": "production",
  "data": { "reference": "01JA0...", "number": "...", "status": "issued", "...": "..." }
}

data holds the record in the same shape the REST API returns for it. environment is production or sandbox.

Responding, retries and auto-disable#

• Answer with any 2xx status within 15 seconds. Anything else, a timeout or a connection error counts as a failed attempt.
• After a failure Bilify tries again after about 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours and 24 hours. That is 7 attempts in total over roughly a day and a half. Then the delivery is marked Failed permanently.
• If 5 deliveries in a row end as Failed permanently, the endpoint is switched off automatically and owners and admins get a notification in the app (bell). Any successful delivery resets the count. The endpoint shows a note that it was disabled after repeated failures. Switch its toggle back on once your server is reachable again.

Recent deliveries and redelivery#

The Recent deliveries card lists the last 30 deliveries with Event, the endpoint URL, Status (Pending, Delivered, Failed, Failed permanently), the HTTP Code your server answered (or No response), Attempts and Created.

Click Redeliver on a row to send it again right away. The attempt counter starts from zero, the original payload is sent again, and it is signed with the endpoint's current secret and a new timestamp. You can also redeliver through the API with POST /api/v1/webhook-deliveries/{reference}/redeliver.

Bilify does not currently delete old delivery records, so the history stays available for your audits.

Edit, pause or remove an endpoint#

From the endpoint's row:

• The toggle switches the endpoint between active and inactive. Inactive endpoints receive nothing; events that happen meanwhile are not queued for later.
• The menu (three dots) has Edit (URL, events, description, active), Regenerate secret and Remove.
• Remove stops all deliveries to that endpoint. Its past delivery history is kept.

Test before going live#

Use the sandbox: add an endpoint inside the sandbox, create test data there, and watch deliveries arrive with "environment": "sandbox". See Sandbox mode.