Webhooks in AccBooks AI

What are webhooks?

Webhooks are HTTP callbacks that AccBooks sends to your server when specific events occur. Instead of polling the API to check for changes, you register a URL and AccBooks pushes event data to it in real time.

Example flow:

1. A customer pays an invoice in AccBooks.
2. AccBooks immediately sends a POST request to your webhook URL.
3. Your system receives the invoice.paid event and triggers your fulfilment workflow.

Setting up a webhook

1. Go to Settings → Integrations → API → Webhooks → Add webhook.
2. Enter your endpoint URL — the HTTPS URL on your server that will receive webhook events.
3. Select the events you want to receive (see list below).
4. Click Save.
5. AccBooks sends a test event to your URL to verify it’s reachable.

Your endpoint must return a 2xx HTTP status within 10 seconds. If it doesn’t, AccBooks retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s).

Available events

Event	Triggered when
transaction.created	A new bank transaction is imported
transaction.classified	A transaction is classified (manually or by AI)
invoice.created	A new invoice is created
invoice.sent	An invoice is emailed to a customer
invoice.paid	An invoice is fully paid
invoice.overdue	An invoice passes its due date unpaid
payroll.run_finalised	A payroll run is finalised
vat.return_filed	A VAT return is submitted to HMRC
bank_feed.error	A bank feed disconnects or errors
bank_feed.synced	A bank feed successfully syncs new data
company.year_end_closed	The year-end close process is completed

Webhook payload format

All webhooks send a JSON payload:

{
  "id": "evt_01HXYZ123",
  "type": "invoice.paid",
  "created_at": "2026-04-15T14:32:00Z",
  "data": {
    "invoice_id": "inv_0123",
    "customer_id": "cust_456",
    "amount": 2500.00,
    "currency": "GBP",
    "paid_at": "2026-04-15T14:31:55Z"
  }
}

Verifying webhook authenticity

AccBooks signs every webhook request with a shared secret (HMAC-SHA256). Verify the signature before processing the event:

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler:
signature = request.headers.get('AccBooks-Signature')
is_valid = verify_signature(request.body, signature, your_webhook_secret)

The shared secret is shown when you create the webhook in AccBooks.

Handling duplicate events

Network issues can occasionally cause AccBooks to send the same event twice. Each event has a unique id — store processed event IDs and check for duplicates before processing.

Webhook logs

Go to Settings → Integrations → API → Webhooks → [your endpoint] → Logs to see:

• All events sent in the last 7 days.
• The HTTP status code returned by your server.
• Response time.
• Any delivery failures and retry attempts.

Failed events can be manually retried from the logs page.

Disabling and re-enabling

Toggle the Active switch on any webhook to temporarily disable it without deleting the configuration. Useful during maintenance windows on your server.