#Webhooks

#What it is

A webhook is an automatic message that Threadline sends to another tool the moment something happens. For example: "a customer just completed a lead form" or "a deal was won".

You give Threadline 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

Threadline 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 Threadline, type it into the CRM, tell the team in chat. This is slow and things get missed.

With webhooks, Threadline 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 Threadline ringing a doorbell at an address you gave it, and handing over a note.

1. Something happens in Threadline, such as a deal being won.
2. Threadline checks which endpoints asked to hear about that event.
3. It sends each one a small message with the details, in a standard format called JSON.
4. The other tool receives it and does whatever you set it up to do.

Webhooks or the API? A webhook is Threadline telling another tool that something happened. The API is another tool asking Threadline 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

1. Go to Webhooks and click Add endpoint.
2. Paste the URL that should receive the messages. Your other tool gives you this.
3. Tick the events this endpoint should receive. It gets only those.
4. Save.

Threadline now shows a signing secret for this endpoint.

#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 Threadline

#What it is

Every webhook carries a signature: a code that only Threadline 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

Threadline 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, Threadline tries again automatically, waiting a little longer each time.

After several failed attempts, the delivery is marked failed and Threadline 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 Threadline. See Troubleshooting.

I lost the signing secret. It cannot be shown again. Delete the endpoint and add it again to get a new one.

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.