# Webhooks > Hear about every conversation as it happens, signed so you know it came from Aigently. A webhook receiver is an address on your server that the platform POSTs events to. Add one in the console under **Webhooks**, choose its events, and keep its signing secret, which is shown once. ## Events about a conversation | Event | When | |---|---| | `conversation.started` | A call was answered, a browser caller joined, or a chat's first message arrived. | | `conversation.ended` | Once, the first time a conversation ends — answered or not. | | `conversation.updated` | Something changed after the end — an outcome corrected, for one. | | `conversation.analyzed` | The analysis finished: outcome, sentiment, the checks it scored. | | `conversation.recording_ready` | The recording is stored. It carries no link: [ask for one](/guides/conversations#the-recording) when you need it. | | `conversation.deleted` | Removed by retention, from the console, [through the API](/guides/conversations#delete-one), or with its agent or project. | | `conversation.transcript` | The whole transcript. It carries what was said, so it is off until you choose it. | ## Events about an agent `agent.updated` is sent when an agent's fields change: the [variables](/guides/variables) a conversation can start with, the answers it collects, or what its analysis writes. An edit to a published agent takes effect from the next conversation, so an edit that adds a required variable is one your integration needs to hear about before its next call. It carries the agent as [Get an agent](/reference/getAgent) describes it, with the three lists, `analysis_enabled`, and `changed`, which names the lists that changed. Each list has a `version`: keep it, and you can tell a change to the fields from any other edit. An edit that changes no field — a new name, reworded instructions with the same placeholders — sends nothing. It goes to live receivers only: an agent's fields are not test data. A receiver made before the event existed hears it once `agent.updated` is added to its `events`. ## Events about a campaign A [campaign](/guides/campaigns) sends `campaign.started`, `campaign.paused`, `campaign.completed` and `campaign.cancelled` as it moves — whether you moved it, somebody did in the console, or it paused itself — and `campaign.contact_finished` with one person's final result. They go to live receivers only. There are more — forms, workflow steps, appointments, handovers — listed beside each receiver in the console. Every event of the last 30 days is also in the [event feed](/guides/events), whether or not a receiver heard it. Which events a call sends as it ends is in the [endings table](/guides/outbound-calls#how-a-call-ends). ## What you receive ```json { "id": "0f9a7c2e-5b1d-4e8a-9c3f-2d6b8e1a4c7f", "event": "conversation.ended", "created_at": "2026-10-07T09:14:03.120394+00:00", "livemode": true, "revision": 6, "data": { "object": "conversation", "id": "5f0c9a52-…", "status": "completed", "…": "…" } } ``` `data` is the [conversation](/reference/objects/Conversation), as the API reads it. `id` is the event's own id: the same event delivered twice has the same `id`, so keep the ones you have seen. Events can arrive out of order — keep the copy with the higher `revision`. Answer `2xx` quickly and do the work afterwards; anything else is retried with growing waits. ## Check the signature Every delivery is signed with your receiver's secret, the [Standard Webhooks](https://www.standardwebhooks.com/) way — so any of that standard's libraries checks it — in three headers: `webhook-id`, `webhook-timestamp` and `webhook-signature`. Check it against the body **exactly as it arrived**, before parsing it, and refuse anything older than five minutes. This function does all of it, in your language: **curl** ```sh #!/bin/sh # Check a saved delivery's signature by hand, with openssl: the body on standard input, the three # headers in WEBHOOK_ID, WEBHOOK_TIMESTAMP and WEBHOOK_SIGNATURE. A server should use one of the # other languages, which compare in constant time. set -eu body="$(mktemp)" trap 'rm -f "$body"' EXIT cat > "$body" now="$(date +%s)" age=$((now - WEBHOOK_TIMESTAMP)) if [ "${age#-}" -gt 300 ]; then echo "timestamp outside the tolerance" >&2 exit 1 fi key="$(printf '%s' "${AIGENTLY_WEBHOOK_SECRET#whsec_}" | base64 -d | od -An -v -tx1 | tr -d ' \n')" expected="$({ printf '%s.%s.' "$WEBHOOK_ID" "$WEBHOOK_TIMESTAMP"; cat "$body"; } \ | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$key" -binary | base64)" for entry in $WEBHOOK_SIGNATURE; do if [ "$entry" = "v1,$expected" ]; then echo "verified" exit 0 fi done echo "signature does not match" >&2 exit 1 ``` **JavaScript** ```js // Check a webhook's signature, then read its event. // The same function checks a context lookup request, with the lookup's secret. import { createHmac, timingSafeEqual } from "node:crypto"; import { text } from "node:stream/consumers"; const TOLERANCE_SECONDS = 5 * 60; // `body` is the request body exactly as it arrived: parse it only after this has checked it. // `headers` has lowercase names, as Node gives them. export function unwrap(body, headers, secret) { const id = headers["webhook-id"]; const timestamp = headers["webhook-timestamp"]; const signatures = headers["webhook-signature"]; if (!id || !timestamp || !signatures) throw new Error("missing webhook headers"); if (!(Math.abs(Date.now() / 1000 - Number(timestamp)) <= TOLERANCE_SECONDS)) { throw new Error("timestamp outside the tolerance"); } const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest(); const matched = signatures.split(" ").some((entry) => { const [version, signature] = entry.split(","); if (version !== "v1" || !signature) return false; const offered = Buffer.from(signature, "base64"); return offered.length === expected.length && timingSafeEqual(offered, expected); }); if (!matched) throw new Error("signature does not match"); return JSON.parse(body); } // Try it with a delivery: the body on standard input, the three headers in the environment. const event = unwrap( await text(process.stdin), { "webhook-id": process.env.WEBHOOK_ID, "webhook-timestamp": process.env.WEBHOOK_TIMESTAMP, "webhook-signature": process.env.WEBHOOK_SIGNATURE, }, process.env.AIGENTLY_WEBHOOK_SECRET, ); console.log(`verified ${event.event} ${event.id}`); ``` **Python** ```python # Check a webhook's signature, then read its event. # The same function checks a context lookup request, with the lookup's secret. import base64 import hashlib import hmac import json import os import sys import time TOLERANCE_SECONDS = 5 * 60 def unwrap(body: bytes, headers, secret: str) -> dict: """The event, once its signature is checked. Raises ValueError otherwise. `body` is the request body exactly as it arrived: parse it only after this has checked it. `headers` is any mapping of the request's headers; most frameworks read theirs in any case. """ message_id = headers.get("webhook-id") timestamp = headers.get("webhook-timestamp") signatures = headers.get("webhook-signature") if not message_id or not timestamp or not signatures: raise ValueError("missing webhook headers") if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS: raise ValueError("timestamp outside the tolerance") key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{message_id}.{timestamp}.".encode() + body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() for entry in signatures.split(" "): version, _, signature = entry.partition(",") if version == "v1" and hmac.compare_digest(signature, expected): return json.loads(body) raise ValueError("signature does not match") if __name__ == "__main__": # Try it with a delivery: the body on standard input, the three headers in the environment. event = unwrap( sys.stdin.buffer.read(), { "webhook-id": os.environ["WEBHOOK_ID"], "webhook-timestamp": os.environ["WEBHOOK_TIMESTAMP"], "webhook-signature": os.environ["WEBHOOK_SIGNATURE"], }, os.environ["AIGENTLY_WEBHOOK_SECRET"], ) print("verified", event["event"], event["id"]) ``` **Go** ```go // Check a webhook's signature, then read its event. // The same function checks a context lookup request, with the lookup's secret. package main import ( "crypto/hmac" "crypto/sha256" "encoding/base64" "encoding/json" "errors" "fmt" "io" "net/http" "os" "strconv" "strings" "time" ) const toleranceSeconds = 5 * 60 // Unwrap checks the signature on a webhook and returns its event. body is the request body exactly // as it arrived: parse it only after this has checked it. func Unwrap(body []byte, headers http.Header, secret string) (map[string]any, error) { id := headers.Get("webhook-id") timestamp := headers.Get("webhook-timestamp") signatures := headers.Get("webhook-signature") if id == "" || timestamp == "" || signatures == "" { return nil, errors.New("missing webhook headers") } sent, err := strconv.ParseInt(timestamp, 10, 64) if err != nil || time.Since(time.Unix(sent, 0)).Abs() > toleranceSeconds*time.Second { return nil, errors.New("timestamp outside the tolerance") } key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_")) if err != nil { return nil, errors.New("not a webhook signing secret") } mac := hmac.New(sha256.New, key) mac.Write([]byte(id + "." + timestamp + ".")) mac.Write(body) expected := mac.Sum(nil) for _, entry := range strings.Split(signatures, " ") { version, signature, _ := strings.Cut(entry, ",") offered, err := base64.StdEncoding.DecodeString(signature) if version == "v1" && err == nil && hmac.Equal(offered, expected) { var event map[string]any if err := json.Unmarshal(body, &event); err != nil { return nil, err } return event, nil } } return nil, errors.New("signature does not match") } func main() { // Try it with a delivery: the body on standard input, the three headers in the environment. body, _ := io.ReadAll(os.Stdin) headers := http.Header{} headers.Set("webhook-id", os.Getenv("WEBHOOK_ID")) headers.Set("webhook-timestamp", os.Getenv("WEBHOOK_TIMESTAMP")) headers.Set("webhook-signature", os.Getenv("WEBHOOK_SIGNATURE")) event, err := Unwrap(body, headers, os.Getenv("AIGENTLY_WEBHOOK_SECRET")) if err != nil { fmt.Fprintln(os.Stderr, err) os.Exit(1) } fmt.Println("verified", event["event"], event["id"]) } ``` **Java** ```java // Check a webhook's signature. Once it passes, read the event with your JSON library. // The same method checks a context lookup request, with the lookup's secret. import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.util.Base64; import java.util.Map; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public class Main { static final long TOLERANCE_SECONDS = 5 * 60; /** * The body, once its signature is checked; throws otherwise. `body` is the request body exactly * as it arrived, and `headers` has lowercase names. */ static String unwrap(byte[] body, Map headers, String secret) throws Exception { String id = headers.get("webhook-id"); String timestamp = headers.get("webhook-timestamp"); String signatures = headers.get("webhook-signature"); if (id == null || timestamp == null || signatures == null) { throw new SecurityException("missing webhook headers"); } long now = System.currentTimeMillis() / 1000; if (!timestamp.matches("\\d{1,12}") || Math.abs(now - Long.parseLong(timestamp)) > TOLERANCE_SECONDS) { throw new SecurityException("timestamp outside the tolerance"); } byte[] key = Base64.getDecoder().decode(secret.replaceFirst("^whsec_", "")); Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(key, "HmacSHA256")); mac.update((id + "." + timestamp + ".").getBytes(StandardCharsets.UTF_8)); byte[] expected = mac.doFinal(body); for (String entry : signatures.split(" ")) { String[] parts = entry.split(",", 2); if (parts.length != 2 || !parts[0].equals("v1")) { continue; } byte[] offered; try { offered = Base64.getDecoder().decode(parts[1]); } catch (IllegalArgumentException malformed) { continue; } if (MessageDigest.isEqual(offered, expected)) { return new String(body, StandardCharsets.UTF_8); } } throw new SecurityException("signature does not match"); } public static void main(String[] args) throws Exception { // Try it with a delivery: the body on standard input, the three headers in the environment. String event = unwrap( System.in.readAllBytes(), Map.of( "webhook-id", System.getenv("WEBHOOK_ID"), "webhook-timestamp", System.getenv("WEBHOOK_TIMESTAMP"), "webhook-signature", System.getenv("WEBHOOK_SIGNATURE")), System.getenv("AIGENTLY_WEBHOOK_SECRET")); System.out.println("verified " + event); } } ``` **C#** ```csharp // Check a webhook's signature, then read its event. // The same function checks a context lookup request, with the lookup's secret. using System.Security.Cryptography; using System.Text; using System.Text.Json; // Try it with a delivery: the body on standard input, the three headers in the environment. using var input = new MemoryStream(); Console.OpenStandardInput().CopyTo(input); using var webhookEvent = Webhooks.Unwrap( input.ToArray(), new Dictionary { ["webhook-id"] = Environment.GetEnvironmentVariable("WEBHOOK_ID"), ["webhook-timestamp"] = Environment.GetEnvironmentVariable("WEBHOOK_TIMESTAMP"), ["webhook-signature"] = Environment.GetEnvironmentVariable("WEBHOOK_SIGNATURE"), }, Environment.GetEnvironmentVariable("AIGENTLY_WEBHOOK_SECRET") ?? ""); var root = webhookEvent.RootElement; Console.WriteLine($"verified {root.GetProperty("event")} {root.GetProperty("id")}"); static class Webhooks { const long ToleranceSeconds = 5 * 60; // The event, once its signature is checked; throws otherwise. `body` is the request body // exactly as it arrived: parse it only after this has checked it. public static JsonDocument Unwrap( byte[] body, IReadOnlyDictionary headers, string secret) { if (headers.GetValueOrDefault("webhook-id") is not { Length: > 0 } id || headers.GetValueOrDefault("webhook-timestamp") is not { Length: > 0 } timestamp || headers.GetValueOrDefault("webhook-signature") is not { Length: > 0 } signatures) { throw new CryptographicException("missing webhook headers"); } if (!long.TryParse(timestamp, out var sent) || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - sent) > ToleranceSeconds) { throw new CryptographicException("timestamp outside the tolerance"); } var key = Convert.FromBase64String(secret.StartsWith("whsec_") ? secret[6..] : secret); var signed = Encoding.UTF8.GetBytes($"{id}.{timestamp}.").Concat(body).ToArray(); var expected = Encoding.ASCII.GetBytes(Convert.ToBase64String(HMACSHA256.HashData(key, signed))); foreach (var entry in signatures.Split(' ')) { var parts = entry.Split(',', 2); if (parts.Length == 2 && parts[0] == "v1" && CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(parts[1]), expected)) { return JsonDocument.Parse(body); } } throw new CryptographicException("signature does not match"); } } ``` **PHP** ```php TOLERANCE_SECONDS) { throw new RuntimeException("timestamp outside the tolerance"); } $key = base64_decode(preg_replace('/^whsec_/', "", $secret), true); $expected = base64_encode(hash_hmac("sha256", "$id.$timestamp.$body", (string) $key, true)); foreach (explode(" ", $signatures) as $entry) { [$version, $signature] = array_pad(explode(",", $entry, 2), 2, ""); if ($version === "v1" && hash_equals($expected, $signature)) { return json_decode($body, true, flags: JSON_THROW_ON_ERROR); } } throw new RuntimeException("signature does not match"); } // Try it with a delivery: the body on standard input, the three headers in the environment. $event = aigently_unwrap( file_get_contents("php://stdin"), [ "webhook-id" => (string) getenv("WEBHOOK_ID"), "webhook-timestamp" => (string) getenv("WEBHOOK_TIMESTAMP"), "webhook-signature" => (string) getenv("WEBHOOK_SIGNATURE"), ], (string) getenv("AIGENTLY_WEBHOOK_SECRET"), ); echo "verified {$event["event"]} {$event["id"]}\n"; ``` The same function checks a [context lookup](/guides/inbound-calls) request, with the lookup's secret. Receivers made before this signature existed also get `X-Agently-Signature: t=