How to Send Job Changes to Another Tool
Result: HeadHoncho calls your web address each time a job changes, so another tool can react. Time: about five minutes if you already have an address ready.
What You Need First
- An API key. See Connect An AI App for how to make one. The key needs Read on Jobs and Read and change on Company settings.
- A web address that accepts a signed POST: a Zapier or n8n "catch hook", or your own code.
- The address must start with https, be public, and use port 443 or a port from 1024 up.
Webhooks come with every plan. Each change delivered costs 1 credit, however many tries it takes. A failed try costs nothing.
Set Up Job Webhooks in Seven Steps
- Open Automations, then API keys, then the Webhooks tab.
- Press Add webhook.
- Under Key, pick the key it will act as.
- Under Address, paste your https address. Under Name, give it a name you will recognise.
- Under What to send, tick the kinds of change you want, such as a job moving to another status.
- Under Companies, choose Every company the key reaches or Only these. Press Add webhook.
- Copy the Signing secret now. It starts with whsec_ and is shown only once. Press Done, then press Send test on the new webhook.
What Your Address Receives
Each change is one signed POST with a small JSON body: the kind of change, the time, who did it, the job, and a few plain facts. Money amounts, customer details and message text are never in it. Read the job for those. Changes start from the moment you add the webhook. The past is not sent.
Check the signature before you act. It is in the X-HeadHoncho-Signature header: sha256= and the HMAC-SHA256 of the timestamp, a dot and the raw body, made with your secret. Code for cURL, Python and JavaScript is on Webhooks. Answer with any 2xx status within eight seconds. Do the real work after you answer.
How You Know It Worked
- The pill beside the webhook reads Running.
- After Send test, the list under Last deliveries shows a green status code. Press Every try to see each attempt.
- Move a real job to another status and a new delivery appears.
If It Fails
| What You See | What To Do |
|---|---|
| A red No answer or a 4xx or 5xx code | Your address did not accept it. Fix the address, then press Send again on the delivery. |
| Trying again | We retry after 30 seconds, then a minute, then longer, for 24 hours. |
| Paused | After two hours of failures, with at least ten failed tries, it pauses and tells you. Fix the address, then press Resume. What it missed is sent, in order. |
| Key revoked | The key was revoked. Make a new key and a new webhook. |
| Paused for no credits | Add credits. It carries on by itself. |
| Lost the secret | Press New secret. The old one stops at once, so update your receiver first. |
| Address refused | It must be https and public. Private or local addresses are refused. |
A repeat can arrive, and two changes can arrive out of order. Drop repeats by X-HeadHoncho-Event-Id. Full details are on Webhooks.