Webhooks

curl --request PATCH https://api.fish.audio/v1/agent/agents/YOUR_AGENT_ID/config \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "webhooks": {
      "post_call": [
        {
          "url": "https://example.com/fish-webhooks",
          "secret": "your-signing-secret"
        },
        {
          "url": "https://crm.example.com/fish-webhooks",
          "secret": "another-signing-secret"
        }
      ]
    }
  }'

import httpx, os

httpx.patch(
    "https://api.fish.audio/v1/agent/agents/YOUR_AGENT_ID/config",
    headers={"Authorization": f"Bearer {os.environ['FISH_API_KEY']}"},
    json={
        "webhooks": {
            "post_call": [
                {
                    "url": "https://example.com/fish-webhooks",
                    "secret": "your-signing-secret",
                },
                {
                    "url": "https://crm.example.com/fish-webhooks",
                    "secret": "another-signing-secret",
                },
            ]
        }
    },
)

{
  "event": "call.ended",
  "session": {
    "id": "5f3e…",
    "agent_id": "a1b2…",
    "branch_id": "b7d4…",
    "source": "phone",
    "status": "completed",
    "conversation_started_at": "2026-07-23T12:01:12Z",
    "conversation_ended_at": "2026-07-23T12:04:16Z",
    "duration_seconds": 184,
    "end_user_id": "customer-42",
    "metadata": { "order_ref": "SO-1042" },
    "agent_name": "Support agent",
    "config_hash": "sha256:9c41…"
  },
  "ended_reason": "hangup"
}

{
  "event": "call.analyzed",
  "session": {
    "id": "5f3e…",
    "agent_id": "a1b2…",
    "branch_id": "b7d4…",
    "source": "phone",
    "status": "completed",
    "conversation_started_at": "2026-07-23T12:01:12Z",
    "conversation_ended_at": "2026-07-23T12:04:16Z",
    "duration_seconds": 184,
    "end_user_id": "customer-42",
    "metadata": { "order_ref": "SO-1042" },
    "agent_name": "Support agent",
    "config_hash": "sha256:9c41…"
  },
  "analysis": {
    "status": "completed",
    "summary": "Caller asked about a delayed order and accepted a reshipment.",
    "data": [
      {
        "name": "callback_requested",
        "type": "boolean",
        "value": false,
        "rationale": "…"
      }
    ],
    "criteria_results": [
      { "name": "issue_resolved", "result": "success", "rationale": "…" }
    ]
  }
}

{
  "event": "phone_call.dial_finished",
  "dial_status": "answered",
  "answered_by": "human",
  "session": {
    "id": "5f3e…",
    "agent_id": "a1b2…",
    "branch_id": "b7d4…",
    "source": "phone",
    "status": "active",
    "direction": "outbound",
    "dial_status": "answered",
    "answered_by": "human",
    "batch_call_id": null,
    "conversation_started_at": "2026-07-23T12:01:12Z",
    "conversation_ended_at": null,
    "duration_seconds": null,
    "end_user_id": "",
    "metadata": { "lead_ref": "L-2041" },
    "agent_name": "Follow-up agent",
    "config_hash": "sha256:9c41…"
  }
}

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 300;

function verifyWebhook(rawBody, signatureHeader, secret) {
  const elements = new Map(
    (signatureHeader ?? "").split(",").map(el => el.split("=", 2))
  );
  const timestamp = elements.get("t");
  const signature = elements.get("v1");
  if (
    !/^\d+$/.test(timestamp ?? "") ||
    !/^[0-9a-f]{64}$/.test(signature ?? "")
  ) {
    return false;
  }
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) {
    return false;
  }
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300

def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    elements = dict(
        el.split("=", 1) for el in (signature_header or "").split(",") if "=" in el
    )
    timestamp = elements.get("t", "")
    signature = elements.get("v1", "")
    if not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature.encode(), expected.encode())

import express from "express";

const app = express();
const seen = new Set(); // swap for your database

app.post(
  "/fish-webhooks",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.get("X-Fish-Webhook-Signature");
    if (!verifyWebhook(req.body, signature, process.env.FISH_WEBHOOK_SECRET)) {
      return res.status(401).end();
    }
    res.status(200).end(); // acknowledge first, then process

    const payload = JSON.parse(req.body);
    if (payload.event !== "call.analyzed") return;

    const key = `${payload.session.id}:${payload.analysis.finished_at}`;
    if (seen.has(key)) return; // at-least-once delivery: dedupe
    seen.add(key);

    if (payload.analysis.status !== "completed") {
      // skipped (the caller never spoke) or error: no verdict to trust.
      openTicket({
        subject: `Unjudged call ${payload.session.id}`,
        body:
          `Analysis ${payload.analysis.status}` +
          (payload.analysis.error ? `: ${payload.analysis.error}` : ""),
        customer: payload.session.end_user_id,
      });
      return;
    }

    const verdict = payload.analysis.criteria_results.find(
      c => c.name === "issue_resolved"
    );
    if (!verdict || verdict.result === "success") return;

    openTicket({
      subject: `Unresolved call ${payload.session.id}`,
      body:
        `${payload.analysis.summary}\n\n` +
        `issue_resolved: ${verdict.result}. ${verdict.rationale}`,
      customer: payload.session.end_user_id,
    });
  }
);

import json
import os

from fastapi import FastAPI, Header, Request, Response

app = FastAPI()
seen: set[str] = set()  # swap for your database

@app.post("/fish-webhooks")
async def fish_webhooks(
    request: Request,
    x_fish_webhook_signature: str | None = Header(None),
):
    raw = await request.body()
    secret = os.environ["FISH_WEBHOOK_SECRET"]
    if not verify_webhook(raw, x_fish_webhook_signature, secret):
        return Response(status_code=401)

    payload = json.loads(raw)
    if payload["event"] != "call.analyzed":
        return {}

    analysis = payload["analysis"]
    key = f"{payload['session']['id']}:{analysis['finished_at']}"
    if key in seen:  # at-least-once delivery: dedupe
        return {}
    seen.add(key)

    if analysis["status"] != "completed":
        # skipped (the caller never spoke) or error: no verdict to trust.
        detail = f": {analysis['error']}" if analysis.get("error") else ""
        open_ticket(
            subject=f"Unjudged call {payload['session']['id']}",
            body=f"Analysis {analysis['status']}{detail}",
            customer=payload["session"]["end_user_id"],
        )
        return {}

    results = analysis["criteria_results"]
    verdict = next((c for c in results if c["name"] == "issue_resolved"), None)
    if verdict and verdict["result"] != "success":
        open_ticket(
            subject=f"Unresolved call {payload['session']['id']}",
            body=f"{analysis['summary']}\n\n"
            f"issue_resolved: {verdict['result']}. {verdict['rationale']}",
            customer=payload["session"]["end_user_id"],
        )
    return {}