Webhooks
What it is
A webhook is an automatic message that audiencechat sends to another tool the moment something happens. For example: "a customer just completed a lead form" or "a deal was won".
You give audiencechat a web address, called an endpoint, and choose which events it should hear about.
It is an Admin area, reached from Webhooks in the navigation, and needs a plan that includes Webhooks.
The problem it solves
audiencechat is rarely the only tool a business uses. You may have a CRM, a spreadsheet, a team chat such as Slack, or an automation tool such as Zapier, Make or n8n.
Without webhooks, a person must copy information between them by hand: read the lead in audiencechat, type it into the CRM, tell the team in chat. This is slow and things get missed.
With webhooks, audiencechat tells those tools itself, immediately:
- a lead form is completed, and a row is added to your spreadsheet;
- a conversation is handed to a person, and your team chat is notified;
- a deal is won, and your CRM is updated.
How it works
Think of a webhook as audiencechat ringing a doorbell at an address you gave it, and handing over a note.
- Something happens in audiencechat, such as a deal being won.
- audiencechat checks which endpoints asked to hear about that event.
- It sends each one a small message with the details, in a standard format called JSON.
- The other tool receives it and does whatever you set it up to do.
Webhooks or the API? A webhook is audiencechat telling another tool that something happened. The API is another tool asking audiencechat to do or show something. Many setups use both.
You do not need to be a programmer to use webhooks with a tool like Zapier, Make or n8n. They give you an address to paste in. If you are building your own receiver, a developer should read the Integrations & API page for the exact formats.
1. Adding an endpoint
- Go to Webhooks and click Add endpoint.
- Paste the URL that should receive the messages. Your other tool gives you this.
- Tick the events this endpoint should receive. Each one says when it is sent. The endpoint gets only those.
- Save.
audiencechat opens the endpoint's page, which shows:
- its signing secret, this once;
- What we send: the request audiencechat makes, and an example message for each event you ticked;
- Send test, to send one of those examples to your endpoint now;
- the delivery log.
Copy the signing secret now. It is shown only once. You need it if you want to check that messages really come from audiencechat.
Sending a test
Tools such as Zapier, Make and n8n need one message before you can map its fields. Instead of waiting for a real event, open the endpoint, choose an event under What we send and press Send test. audiencechat sends the example shown, signed like a real message, with "test": true added so your receiver can tell it apart. The result shows at once and in the delivery log. A test is sent once and never retried.
2. The events
| Event | Sent when… |
|---|---|
message.received |
A customer sends a message on any channel. |
contact.created |
A new contact appears: someone writes for the first time, or a contact is added by hand or through the API. Imports do not send it. |
conversation.escalated |
A conversation is handed from the AI to a person. The reason is included. |
conversation.closed |
A conversation is closed. |
answer.fallback |
The AI replies that it does not have enough information. Useful for spotting gaps in your knowledge base. |
lead_form.submitted |
Someone finishes a lead form. The answers are included. |
deal.created |
A deal is created. |
deal.stage_changed |
A deal moves to another stage. The old and new stage are included. |
deal.won |
A deal is won. |
deal.lost |
A deal is lost. The reason is included. |
booking.created |
An appointment is booked. |
booking.cancelled |
An appointment is cancelled. The reason is included. |
booking.completed |
An appointment is marked completed. |
The exact contents of each message are listed in Integrations & API.
3. Checking a message really came from audiencechat
What it is
Every webhook carries a signature: a code that only audiencechat and you can produce, because it is made with your signing secret.
The problem it solves
An endpoint is a public web address. Anyone who finds it could send it fake messages, such as a false "deal won". The signature lets your receiver tell real messages from fake ones.
How it works
audiencechat adds a header named X-Threadline-Signature-256 to each message. Its value is sha256= followed by a code. That code is an HMAC-SHA256 of the message body, made with your signing secret.
Your receiver makes the same calculation with the same secret. If its result matches the header, the message is real. If not, it should be rejected.
Many no-code tools skip this step, which is acceptable for low-risk uses. If the webhook triggers anything important, have a developer add the check. Example code is in Integrations & API.
4. Retries
Sometimes the other tool is briefly down. If a delivery fails, because of an error reply, a timeout or no connection, audiencechat tries again automatically, waiting a little longer each time.
After several failed attempts, the delivery is marked failed and audiencechat stops. It does not retry forever.
5. The delivery log
Open an endpoint to see its recent deliveries. Every attempt is listed, with:
- the event;
- whether it succeeded or failed;
- the reply code from the other tool;
- for a failure, the error or the start of the reply.
This is the first place to look when something is not arriving. It usually shows the cause without needing server logs.
Good to know
- An endpoint must be reachable from the internet. An address that only works inside your office network will not receive anything.
- Deleting an endpoint stops deliveries to it at once.
- Webhooks are sent in the background, so they never slow down a reply to a customer.
Common questions
Nothing arrives at my endpoint. Check the delivery log. If every attempt shows a connection error, your server or firewall is blocking requests from audiencechat. See Troubleshooting.
I lost the signing secret. It cannot be shown again. Open the endpoint and press Make a new secret: the new one is shown once, and the endpoint keeps its events and delivery log. Messages are signed with the new secret straight away, so give it to your receiver.
Can I receive only some events? Yes. Each endpoint gets only the events you ticked.
Can a webhook be sent from an automation? Yes. The Call a webhook step in an automation sends a contact's details to an address at the moment you choose.