Alya Books

    Help centre

    Guides for Alya Books and UAE e-invoicing

    العربية

    Webhooks

    Let another system know automatically when an invoice is reported, paid or received. Setup is in the app; the technical details are on docs.alyabooks.ai.

    View as MarkdownOpen in ClaudeOpen in ChatGPT

    A webhook is a web address of your ERP, accounting tool or automation platform that Alya Books calls whenever something happens. Your developer gives you the address; you register it here.

    Steps

    1. Open API access in the sidebar (System group) and choose the Webhooks tab. You need the owner or admin role, or the "Manage webhooks" permission.
    2. Click New webhook and fill in:
      • Target URL: must be a public https:// address. Private or plain http:// addresses are refused.
      • Name and an optional Description.
      • Events: tick the ones you need, or All events.
      • Custom headers if your developer asks for them, and the Active switch.
    3. Click Create webhook. A signing secret is shown once; copy it and pass it to your developer, who uses it to verify each call.
    4. From the row menu, use Send test to check the endpoint, Deliveries to see every attempt with status and response, Pause or Resume, Rotate secret, Edit or Delete.

    Common events

    EventSent when
    invoice.created, invoice.submitted, invoice.reported, invoice.rejectedAn invoice moves through the FTA lifecycle
    invoice.paid, invoice.overduePayment recorded or due date passed
    incoming.created, incoming.validated, incoming.acceptedA supplier invoice arrives and is reviewed
    quote.sent, reminder.sent, document.sentA document leaves by email
    customer.created, product.createdMaster data added

    Good to know

    • Failed calls are retried after at least 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours (retries are sent by a job that runs every 5 minutes); after six attempts the delivery is marked failed and can be retried by hand.
    • A webhook pauses itself after 25 consecutive exhausted deliveries; fix the endpoint and click Resume.
    • Webhooks work for every mode, including Test (simulated), so you can integrate before going live.
    • Each call carries the headers X-Webhook-Event, X-Webhook-Event-Id, X-Webhook-Delivery and X-Webhook-Attempt, the signature in X-Webhook-Signature, and the user agent Webhook-Delivery/1.0; custom header names cannot start with X-Webhook-. Your developer verifies the signature with the signing secret.
    • Payload formats, headers and signature verification: see the developer documentation at docs.alyabooks.ai.

    Still stuck? Contact support