Guide · Helpdesk
Ticket webhooks and the helpdesk API: a how-to for developers
In short
Use the API to push things into the helpdesk, such as a damaged-delivery claim from your order system, and webhooks to hear what happened to them, instead of asking every few minutes. Give each integration its own key with only the rights it needs, check the signature on every delivery, answer at once and do the work after, and expect the same event more than once.
Reviewed 10 November 2026. Terms used: Ticketing system, SLA (service level agreement).
Eight steps to a helpdesk integration that holds up
For the developer connecting an order system, a warehouse tool or an internal dashboard to a helpdesk.
Decide which way each job goes
Push with the API when your system knows something first: an order arrived broken, a refund failed. Listen with webhooks when the helpdesk knows first: a ticket was assigned, resolved or is close to its deadline.
Polling every few minutes is slow and still misses the change that happened in between. Ask the helpdesk only when you need the whole ticket.
One key per integration, with the least it needs
An order system that opens tickets needs to read and write them, not delete them. Give each integration its own key, so you can revoke one without stopping the others, and set an expiry you’ll remember to renew.
Keep keys in your secret store, never in the code or a shared document. Most helpdesks show a key once; if it’s lost, make a new one.
Create tickets your team can act on
Send a subject a person can read in a list, the priority, the category your routing uses and who the customer is. Put your own reference, such as the order number, in a field you can search later.
Before you create a second ticket for the same order, look for the first one. A duplicate splits the conversation and the deadline.
A ticket from an order system Subject: Order TH-104377: table top cracked on arrival
Priority: high · Category: delivery damaged
Customer: the contact on the order
Your reference: order-system / TH-104377
Subscribe only to the events you act on
Each event you take is code you maintain. A warehouse tool may need only “ticket created” and “status changed”; a team dashboard “deadline warning” and “deadline breached”. Leave internal notes out unless your system really needs them.
Check the signature before you trust a delivery
A webhook address is public once anyone sees it. Checking the signature stops forged requests: work out the HMAC of the timestamp and the raw body with your secret, compare it in constant time, and refuse old timestamps so a captured request can’t be replayed.
Use the raw body as it arrived. A body your framework has parsed and rebuilt won’t match the signature.
Answer at once, do the work after
Reply with a 2xx as soon as the request is checked and stored, then process it from a queue. A slow handler times out, and the sender tries again while your first attempt is still running.
The order of work in your handler 1. Read the raw body and the signature header
2. Check the signature and the timestamp
3. Store the event and its id
4. Answer 200
5. Process it from your queue
Expect retries, duplicates and odd order
If your endpoint is down, the sender tries again later with the same event id. Keep the ids you’ve processed and skip a repeat. Don’t assume events arrive in the order they happened: compare their times, or read the ticket again when the order matters.
Test it, watch the log, plan the rotation
Send a test delivery before you go live, and read the delivery log when something looks missing. Decide now how you’ll rotate the secret, and make your check accept two signatures for the overlap, so a rotation never drops a delivery.
Asking the helpdesk every few minutes vs a webhook
When you hear
- Polling the API
- At your next check
- A webhook
- Seconds after it happens
What you might miss
- Polling the API
- A change that came and went between checks
- A webhook
- Nothing, if you answer and keep the log
Load
- Polling the API
- A request every few minutes, change or not
- A webhook
- A request only when something changes
What you build
- Polling the API
- A schedule and a comparison
- A webhook
- An endpoint, a signature check and a queue
Best for
- Polling the API
- A report you rebuild once a day
- A webhook
- Anything a person waits on
How it works in Axonave
A tickets API, signed webhooks and a delivery log.
In Axonave you make keys in Settings → API & webhooks: an axv_ key is shown once, with the scopes tickets:read, tickets:write and tickets:delete, an expiry of 30, 90 or 365 days or none, and up to 25 live keys. A key acts as the person who made it, within their role, at 120 requests a minute, and tickets it creates are marked as coming from the API. The API covers tickets only: list, read, create, edit, status, priority, resolve, close, reopen, tags, messages, the timeline, the survey score, categories and delete. Webhooks cover 13 ticket events, from ticket.created to ticket.sla_breached and ticket.message.created (internal notes only if you ask), up to 20 per workspace. Every delivery is signed in X-Axonave-Signature (t=…,v1=…), goes to HTTPS only and waits 10 seconds; without a 2xx it’s tried 8 times over about a day with the same body and event id. The delivery log keeps 30 days, with redeliver and a test ping, and a webhook failing for 3 days switches off and tells your admins. A new secret signs beside the old one for 24 hours.
- The body is a fixed public shape, never the stored record
- No redirects followed, no private addresses
- Every plan has it, with the helpdesk
Settings → API & webhooks in our demo workspace: a webhook to the order desk’s endpoint and its delivery log, six ticket.created deliveries answered with HTTP 200 in milliseconds, each with a redeliver button.
Common questions
Can the API read contacts, leads or deals?
No. The API covers tickets only, and every other part of Axonave refuses a key. A ticket carries its requester’s name, email and contact or lead id.
Are there webhooks for chats or new leads?
No. Webhooks cover 13 ticket events. A chat that becomes a ticket reaches you as ticket.created.
What happens if our endpoint is down?
Each delivery is tried 8 times over about a day, with the same body and event id, and stays in the delivery log for 30 days so you can redeliver it. A webhook that fails for 3 days switches itself off and your admins get a bell.
How do we tell a retry from a new event?
By the event id in the body. It stays the same in every try and in a redelivery, so keep the ids you’ve processed and skip a repeat.
Which plans have the API?
Every plan, Basic included. The routes come with the helpdesk.
See it working with your own customers.
We reply within one business day by email or WhatsApp.