Webhooks for agent events

Send every new agent conversation and message to your own server or automation tool, signed so you can check it came from Fine Structure.

A webhook is an address on your side that Fine Structure calls when something happens. With agent webhooks, your CRM or an automation tool such as Make can log every customer conversation your agents have, or alert your team when an agent finishes a reply. The screen is at /agent-webhooks. It is written in Hebrew only for now, so the button names below are quoted as the screen shows them.

Create a webhook

1. Click + webhook חדש: Type the address that should receive the events in the URL box, for example your Make scenario's webhook URL. It must start with http:// or https://. Leave the agent ID empty to cover all your agents, or paste one agent's ID.

2. Choose the events: Tick the events you want. Nothing ticked means all of them. Add a short description such as "CRM sync" and click צור (create).

3. Copy the secret: A box shows the signing secret once. Copy it to your server; you use it to check each call. Click הבנתי (got it) when done.

4. Test it: On the webhook's row click בדיקה (test) to send a ping event, then לוג (log) to see each delivery with its status, the HTTP answer and the number of attempts.

No code: send every finished reply to Make or Zapier

Example: a pilates studio wants every conversation of its WhatsApp agent written as a row in a Google Sheet. Make or Zapier can do the writing; Fine Structure only has to tell them when something happened.

1. Get an address from the automation tool: In Make, start a scenario with the Webhooks module and its custom webhook trigger; in Zapier, start a Zap with Webhooks by Zapier and its catch hook trigger. The tool shows an address that starts with https://. Copy it.

2. Paste it in Fine Structure: Open /agent-webhooks, click + webhook חדש and paste the address in כתובת היעד (URL). Tick message.completed to get each finished reply. Click צור and copy the secret that appears once.

3. Choose which agent (optional): Leave מזהה סוכן empty to cover all your agents. For one agent only, open it in My agents: the address bar then ends with agent= and its ID, which starts with agt_. Paste that ID.

4. Send a test: Click בדיקה on the webhook row. In Make or Zapier you should now see a test event arrive; use it to map fields such as data.content (the text) and data.channel into your sheet. לוג shows each delivery and whether it got a 2xx answer.

The words on this screen

Word | What it means

Webhook | An address on your side that Fine Structure calls by itself when something happens, like a doorbell for your system.

Agent ID | The fixed name of one agent inside the platform, such as agt_123. Empty means all agents.

2xx | The family of "OK, received" answers a web address gives (200, 201...). Anything else counts as a failure and is tried again.

HMAC and the secret | A math stamp made from the message and your secret. Only someone with the secret can make the same stamp, so a matching stamp proves the call came from Fine Structure.

X-FSE2-Signature | The header where that stamp arrives. Make and Zapier receive the call without checking it; a developer's server should check it.

Event | Sent when

conversation.created | A new conversation with an agent starts, on any channel.

message.created | A message is written, by the customer or by the agent.

message.completed | The agent finished a reply.

ping | You pressed the test button.

What arrives

Each call is an HTTP POST with a JSON body. The X-FSE2-Signature header holds an HMAC-SHA256 of the raw body made with your secret, starting with sha256=. Check it before you trust the call. Message events include the message text unless that is switched off on the server side.

{
  "event": "message.completed",
  "event_id": "<message id>:message.completed",
  "created_at": "2026-11-14T09:12:04",
  "agent_id": "...",
  "conversation_id": "...",
  "data": {
    "message_id": "...",
    "role": "assistant",
    "status": "completed",
    "channel": "whatsapp",
    "app_id": "...",
    "content": "Hi Dana, your class is booked for Tuesday at 18:00."
  }
}

Answer with any 2xx status. A failed call is tried again up to 6 times, waiting longer each time (30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours), and then stops. Calls can arrive out of order, so use event_id to drop duplicates. Code samples for checking the signature are in the webhooks reference.

Pause, new secret, delete

On each row: השהה pauses it (and הפעל resumes), secret חדש makes a new signing secret and shows it once (the old one stops working), and מחק deletes the webhook after a confirmation.

Questions

Q: Will my webhook see conversations of agents I did not pick?

A: Only if you left the agent ID empty, which means all your agents.

Q: The log shows dead.

A: All 6 attempts failed. Check that the address answers with a 2xx status, then send a test ping.

Q: Is this the same as the contracts webhook?

A: No. Contracts have their own webhook for signed contracts, see Advanced contract tools.

Q: Can I get messages without a server?

A: Yes. Paste the webhook address of an automation tool such as Make or Zapier and build the rest there.

Q: The test does not show up in Make or Zapier.

A: Make sure the scenario or Zap is listening (in Make, run it once so it waits for data), that the address was pasted whole, and that the webhook row is active, not paused. Then click the test again and look at the log.

Q: The log shows 404 or 410.

A: The address no longer exists, for example the scenario was deleted. Copy a fresh address from the tool and create the webhook again.

Related: What an AI agent is, API keys for your account, Advanced contract tools, Send files into a notebook automatically (notebook webhooks), Connect your services (Connections)