Webhooks

Webhooks deliver real-time HTTP POST notifications to your backend servers whenever events occur across your agent channels. Instead of continuously polling, your agents can respond instantly to inbound emails, SMS, and iMessages.

Supported Event Types

Event Type	Channel	Description
Email Events
`email.received`	Email	An inbound email was received, parsed, and stored in an agent inbox.
`email.sent`	Email	An outbound email (send, reply, or forward) was accepted by Wirebox for delivery.
`email.delivered`	Email	Remote SMTP server successfully accepted the outbound message.
`email.bounced`	Email	Outbound email failed delivery (hard or soft bounce, mailbox unavailable, or DMARC/SPF rejection).
`email.failed`	Email	Outbound email failed permanently due to transport or network errors.
SMS Events
`sms.received`	SMS/MMS	An inbound SMS or MMS was received on an agent’s phone number.
iMessage Events
`imessage.received`	iMessage	A user sent an inbound iMessage to an agent.
`imessage.sent`	iMessage	An outbound iMessage was accepted by the gateway.
`imessage.failed`	iMessage	An outbound iMessage send failed.
`imessage.connected`	iMessage	Human paired and connected with the agent.
`imessage.disconnected`	iMessage	Conversation session disconnected.
A2A Events
`a2a.task.created`	A2A	An inbound task was submitted to an agent identity via JSON-RPC.
`a2a.task.updated`	A2A	A task message was appended, metadata updated, or state transitioned.
`a2a.task.progress`	A2A	Worker agent reported intermediate progress (`intent: progress`).
`a2a.task.input_required`	A2A	Worker agent paused task waiting for caller clarification (`intent: ask_caller`).
`a2a.task.completed`	A2A	Task reached terminal success with deliverables (`intent: complete`).
`a2a.task.failed`	A2A	Task was marked failed by worker runtime (`intent: fail`).
`a2a.task.canceled`	A2A	Task was canceled by the requester before completion.
System Events
`test.ping`	System	Diagnostic ping fired from the Console or API to verify endpoint connectivity.

Managing Webhooks

You can configure, inspect, test, and manage webhook subscriptions programmatically via the Python SDK, TypeScript SDK, or the terminal CLI.

Creating a Webhook

Register a new HTTPS endpoint to receive agent events. You can optionally restrict the webhook to a specific agent handle or configure a custom Bearer auth token:

from wirebox import Wirebox

with Wirebox() as wb:
    webhook = wb.webhooks.create(
        url="https://agent.example.com/api/webhooks",
        events=["email.received", "sms.received"],
        agent="eva",
        auth_token="optional_bearer_token"
    )
    print("Webhook ID:", webhook.id)
    print("Signing Secret:", webhook.secret)

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();

const webhook = await wb.webhooks.create({
  url: "https://agent.example.com/api/webhooks",
  events: ["email.received", "sms.received"],
  agent: "eva",
  auth_token: "optional_bearer_token",
});

console.log("Webhook ID:", webhook.id);
console.log("Signing Secret:", webhook.secret);

wirebox webhook create \
  --url https://agent.example.com/api/webhooks \
  --events email.received,sms.received \
  --agent eva \
  --auth-token optional_bearer_token

Listing Webhooks

Query all configured webhook subscriptions across your organization, or filter by agent handle:

from wirebox import Wirebox

with Wirebox() as wb:
    webhooks = wb.webhooks.list(agent="eva")
    for wh in webhooks:
        print(f"[{wh.status}] {wh.id}: {wh.url} ({wh.events})")

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();

const webhooks = await wb.webhooks.list({ agent: "eva" });
for (const wh of webhooks) {
  console.log(`[${wh.status}] ${wh.id}: ${wh.url} (${wh.events.join(", ")})`);
}

# Formatted terminal table
wirebox webhook list --agent eva

# Raw JSON (ideal for subagent automation or jq)
wirebox webhook list --agent eva --json

Testing Webhook Connectivity

Send an instant test.ping event to verify network routing, SSL handshakes, and receiver response times:

from wirebox import Wirebox

with Wirebox() as wb:
    result = wb.webhooks.ping("whk_01J8DEF456GHI789")
    print("Ping success:", result.success, "Latency:", result.latency_ms)

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();

const result = await wb.webhooks.test("whk_01J8DEF456GHI789");
console.log("Ping success:", result.success, "Latency:", result.latency_ms);

wirebox webhook test whk_01J8DEF456GHI789

Rotating Signing Secrets

Immediately invalidate an existing HMAC signing secret and generate a fresh replacement:

from wirebox import Wirebox

with Wirebox() as wb:
    res = wb.webhooks.rotate_secret("whk_01J8DEF456GHI789")
    print("New Secret:", res.secret)

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();

const res = await wb.webhooks.rotateSecret("whk_01J8DEF456GHI789");
console.log("New Secret:", res.secret);

wirebox webhook rotate-secret whk_01J8DEF456GHI789

Deleting a Webhook

Permanently remove a webhook subscription:

from wirebox import Wirebox

with Wirebox() as wb:
    wb.webhooks.delete("whk_01J8DEF456GHI789")
    print("Webhook deleted successfully.")

import { Wirebox } from "@wirebox-sh/sdk";

const wb = new Wirebox();

await wb.webhooks.delete("whk_01J8DEF456GHI789");
console.log("Webhook deleted successfully.");

wirebox webhook delete whk_01J8DEF456GHI789

Inbound Payload Example

When an event triggers, Wirebox dispatches a structured JSON payload to your webhook URL:

{
  "id": "evt_01J8DEF456GHI789",
  "event_type": "email.received",
  "timestamp": "2026-09-14T10:00:00Z",
  "data": {
    "message": {
      "id": "msg_01J8ABC123XYZ",
      "mailbox_address": "eva@wireboxmail.com",
      "agent_handle": "eva",
      "thread_id": "thrd_01J8XYZ987ABC",
      "from": "Alex Customer <alex@example.com>",
      "to": ["eva@wireboxmail.com"],
      "cc": [],
      "subject": "Question regarding my API quota",
      "snippet": "Hi Eva, how can I upgrade my team's quota?",
      "sender_access": "default_allowed",
      "created_at": "2026-09-14T10:00:00Z"
    }
  }
}

Authentication & Verification

Wirebox provides two complementary layers of authentication to ensure incoming webhooks originate legitimately from Wirebox.

1. Custom Auth Token (Bearer Authentication)

The simplest method. When registering a webhook endpoint, supply an optional auth_token:

Authorization: Bearer my-custom-secret-token

Your receiving server simply validates this header:

from fastapi import FastAPI, Header, HTTPException

app = FastAPI()
EXPECTED_TOKEN = "Bearer my-custom-secret-token"

@app.post("/api/webhooks")
async def receive_webhook(authorization: str = Header(None)):
    if authorization != EXPECTED_TOKEN:
        raise HTTPException(status_code=401, detail="Unauthorized")
    return {"received": True}

if (req.headers["authorization"] !== `Bearer ${process.env.WEBHOOK_SECRET}`) {
  return res.status(401).send("Unauthorized");
}

2. Zero-Trust HMAC-SHA256 Verification

For cryptographic tamper-proofing, every webhook endpoint is issued a signing secret (whsec_...). Wirebox signs the payload using HMAC-SHA256 and includes the signature in the header:

X-Wirebox-Signature: sha256=9a8b7c6d5e4f3a2b1c0...
X-Wirebox-Timestamp: 1726051200
X-Wirebox-Request-ID: req_01J8ABC123XYZ

The signed string is built from the request ID, the epoch-seconds timestamp, and the exact raw request body:

string_to_sign = request_id + "." + timestamp + "." + raw_body

Deliveries with no request ID fall back to timestamp + "." + raw_body.

Official SDK Verification (Recommended)

Both the Python and TypeScript SDKs provide built-in, timing-safe verification:

from wirebox import verify_webhook

# In your FastAPI, Flask, or Django handler:
is_valid = verify_webhook(
    payload=raw_body_bytes,
    headers=request.headers,
    secret="whsec_your_signing_secret",
    tolerance_seconds=300  # 5-minute replay attack window
)

if not is_valid:
    raise HTTPException(status_code=401, detail="Invalid signature")

import { verifyWebhook } from "@wirebox-sh/sdk";

// In your Express, Next.js, or Hono handler:
const isValid = await verifyWebhook({
  payload: rawBody,          // exact, unparsed request body
  headers: req.headers,
  secret: process.env.WIREBOX_WEBHOOK_SECRET!,
  toleranceMs: 300_000,      // 5-minute replay attack window
});

if (!isValid) {
  res.status(401).send("Invalid signature");
}

If your framework hands you a standard Web Request (Next.js App Router, Hono, Cloudflare Workers), you can pass it directly:

const isValid = await verifyWebhook(req, process.env.WIREBOX_WEBHOOK_SECRET!);

Manual HMAC Verification

If you are implementing verification manually without the SDK:

import hmac
import hashlib
import time

def verify_wirebox_signature(
    raw_body: bytes,
    headers: dict,
    secret: str,
    tolerance: int = 300,
) -> bool:
    signature = headers.get("x-wirebox-signature", "")
    request_id = headers.get("x-wirebox-request-id", "")
    timestamp = headers.get("x-wirebox-timestamp", "")
    if not signature or not timestamp:
        return False

    # Replay protection (timestamp is epoch seconds)
    if abs(time.time() - int(timestamp)) > tolerance:
        return False

    received = signature[len("sha256="):] if signature.startswith("sha256=") else signature
    prefix = f"{request_id}." if request_id else ""
    signed = f"{prefix}{timestamp}.".encode("utf-8") + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(received, expected)

import crypto from "node:crypto";

export function verifyWireboxSignature(
  rawBody: string,
  headers: Record<string, string | string[] | undefined>,
  secret: string,
  toleranceSeconds = 300
): boolean {
  const signature = (headers["x-wirebox-signature"] as string) || "";
  const requestId = (headers["x-wirebox-request-id"] as string) || "";
  const timestamp = (headers["x-wirebox-timestamp"] as string) || "";
  if (!signature || !timestamp) return false;

  // 1. Replay protection (timestamp is epoch seconds)
  const currentTime = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTime - parseInt(timestamp, 10)) > toleranceSeconds) {
    return false;
  }

  // 2. Compute expected signature: [requestId.]timestamp.rawBody
  const received = signature.startsWith("sha256=") ? signature.slice(7) : signature;
  const prefix = requestId ? `${requestId}.` : "";
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${prefix}${timestamp}.${rawBody}`, "utf8")
    .digest("hex");

  // 3. Constant-time comparison
  if (received.length !== expected.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(received, "hex"),
    Buffer.from(expected, "hex")
  );
}

Idempotency & Timeouts

Idempotency: Every delivery carries a unique, stable id. If your server receives the same id more than once, safely acknowledge and discard the duplicate.
Timeouts: Wirebox waits up to 10 seconds for your endpoint to respond. Deliveries are attempted once — there is no automatic retry — so respond with 2xx quickly and queue heavier work asynchronously on your side.

To configure webhooks programmatically, refer to the REST API Reference:

Get Started

Capabilities

Integrations

Supported Event Types

Managing Webhooks

Creating a Webhook

Listing Webhooks

Testing Webhook Connectivity

Rotating Signing Secrets

Deleting a Webhook

Inbound Payload Example

Authentication & Verification

1. Custom Auth Token (Bearer Authentication)

2. Zero-Trust HMAC-SHA256 Verification

Official SDK Verification (Recommended)

Manual HMAC Verification

Idempotency & Timeouts

​Supported Event Types

​Managing Webhooks

​Creating a Webhook

​Listing Webhooks

​Testing Webhook Connectivity

​Rotating Signing Secrets

​Deleting a Webhook

​Inbound Payload Example

​Authentication & Verification

​1. Custom Auth Token (Bearer Authentication)

​2. Zero-Trust HMAC-SHA256 Verification

​Official SDK Verification (Recommended)

​Manual HMAC Verification

​Idempotency & Timeouts

​Related APIs

Supported Event Types

Managing Webhooks

Creating a Webhook

Listing Webhooks

Testing Webhook Connectivity

Rotating Signing Secrets

Deleting a Webhook

Inbound Payload Example

Authentication & Verification

1. Custom Auth Token (Bearer Authentication)

2. Zero-Trust HMAC-SHA256 Verification

Official SDK Verification (Recommended)

Manual HMAC Verification

Idempotency & Timeouts

Related APIs