Webhooks

A webhook automatically sends the full transcript of a session to the address of your choice as soon as it ends, for example at the end of a call with your callbot. Use it to feed your CRM, archive conversations in your ticketing tool or trigger processing after each call. Each delivery is signed (HMAC-SHA256), so your server can check that it really comes from Flowtative.

How it worksCopy Anchor Link

1. You create a webhook in Settings > Webhooks: a label and a destination URL.
2. You link it to one or more agents from the agent editor, Webhooks section.
3. At the end of each session of an agent, Flowtative sends the transcript as a POST to every webhook that is linked to that agent, active and subscribed to the BOT_SESSION_ENDED event.

Before you startCopy Anchor Link

• Prepare a public https:// URL that can receive a POST request. http:// URLs are refused ("HTTPS required.").
• Plan a safe place on the server side to store the signing secret. It is shown only once.

Create a webhookCopy Anchor Link

1. Open Settings, then the Webhooks tab.
2. Click New webhook.
3. Fill in the fields below.
4. Click Create and get the secret.
5. In the Signing secret window, click Copy, store the secret on your server, then click I have copied the secret.

The webhook is created active and subscribed to the BOT_SESSION_ENDED event (end of bot session).

If creation succeeds but the secret could not be generated, a message says "Webhook created, but without a signing secret: …". The webhook exists: generate its secret with the key icon.

Link a webhook to an agentCopy Anchor Link

1. Open the agent in the editor, then the Webhooks section (Intelligence group).
2. Tick the webhooks that should receive this agent's transcripts.
3. Save the agent.

You can also click Create a webhook for this agent: the form creates the webhook, subscribes it to BOT_SESSION_ENDED and ticks it right away (Create and link). The secret is shown the same way.

The list flags situations to fix:

The Manage webhooks (URL, secret, delivery log) link takes you back to the settings.

Manage your webhooksCopy Anchor Link

Each webhook appears as a card with its label, URL and events. Beyond 10 webhooks, a Filter by label or URL… bar and pagination appear.

Failed deliveries logCopy Anchor Link

Only failures are logged. When everything works, the panel says "No delivery error — only failures are logged.". Each line shows the date and the error description. Click it to see the exact content that was to be sent. The Refresh button reloads the log.

Renew the secretCopy Anchor Link

1. Click the key icon (Generate a new HMAC secret).
2. The message "Invalidates the old signature — confirm" appears. Click confirm.
3. Copy the new secret and update it on your server.

Verify the signatureCopy Anchor Link

Each delivery carries two HTTP headers:

The signature is computed as v1 = HMAC-SHA256(secret, timestamp + "." + raw body). To verify it:

1. Read both headers. Reject the request if one is missing.
2. Reject the request if the timestamp is older than about 5 minutes. This protects you against the replay of an old delivery.
3. Recompute the signature on the raw body, before any JSON decoding, and compare it with the v1 value using a constant-time comparison.

The secret window offers these ready-to-paste snippets in Node.js and Python:

import crypto from "node:crypto";

function verify(rawBody, headers, secret, toleranceSeconds = 300) {
  const timestamp = headers["x-via-timestamp"];
  const v1 = headers["x-via-signature"]?.split(",")
    .find((p) => p.startsWith("v1="))?.slice(3);
  if (!timestamp || !v1) return false;
  const age = Math.floor(Date.now() / 1000) - Number(timestamp);
  if (age < 0 || age > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(timestamp + ".").update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
}

Example: feed the CRM after each callCopy Anchor Link

Your customer service runs an appointment-booking callbot and you want each conversation in the customer's CRM record.

1. Your technical team exposes https://crm.exemple.com/hooks/flowtative, which verifies the signature and then attaches the transcript to the contact by phone number.
2. You create the CRM webhook with this URL and hand the secret to the technical team.
3. In the callbot editor, Webhooks section, you tick CRM and save.
4. You make a test call, then check the Failed deliveries log: if it is empty, the delivery succeeded.

Best practicesCopy Anchor Link

• Answer quickly on the server side (a simple acknowledgment), then process the transcript in the background.
• Use one webhook per receiving system rather than one URL that redistributes: you keep a readable failure log for each.
• Disable a webhook rather than deleting it during maintenance of the receiving server: links to agents are kept.

Learn moreCopy Anchor Link