Webhooks

Webhooks deliver real-time events to your endpoints. Use them to trigger actions when emails arrive, extractions complete, or waits finish.

Webhook vs Polling

Webhooks are the preferred way to receive events. They reduce latency and API usage compared to polling.

Event Types

AgentInbox sends webhooks for the following events. Each event includes a payload with relevant data.

email.received

Fired when a new email arrives in an inbox.

otp.extracted

Fired when an OTP is successfully extracted from an email.

magic_link.extracted

Fired when a magic link is extracted from an email.

password_reset.extracted

Fired when a password reset link is extracted.

wait.completed

Fired when a wait completes, successfully or timed out.

inbox.expired

Fired when an inbox reaches its TTL and expires.

Setup

Configure webhook endpoints in the AgentInbox dashboard. You can set multiple endpoints and filter by event type.

Dashboard configuration

Settings > Webhooks > Add Endpoint
URL: https://your-app.com/webhooks/AgentInbox
Events: email.received, otp.extracted
Secret: whsec_...

Verification

Verify webhook signatures to ensure events are sent by AgentInbox. Each request includes a signature header computed with your webhook secret.

Security Best Practice

Always verify webhook signatures before processing the payload. This prevents spoofed requests from unauthorized sources.

typescript

import { verifyWebhook } from "AgentInbox";
 
app.post("/webhooks/AgentInbox", (req, res) => {
  const payload = req.body;
  const signature = req.headers["x-AgentInbox-signature"];
 
  const isValid = verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET);
  if (!isValid) return res.status(401).send("Invalid signature");
 
  // Process event
  console.log(payload.event, payload.data);
  res.status(200).send("OK");
});

python

from AgentInbox import verify_webhook
 
@app.post("/webhooks/AgentInbox")
def handle_webhook(request):
    payload = request.body
    signature = request.headers.get("x-AgentInbox-signature")
 
    if not verify_webhook(payload, signature, os.environ["WEBHOOK_SECRET"]):
        return Response(status=401)
 
    print(payload["event"], payload["data"])
    return Response(status=200)

POST/webhooks/AgentInbox

Example webhook endpoint receiving an event

Headers

Name	Type	Required	Description
x-AgentInbox-signature	string	Required	HMAC-SHA256 signature of the payload.
x-AgentInbox-timestamp	integer	Required	Unix timestamp of when the event was sent.

Payload

HTTP 200

{
  "event": "email.received",
  "timestamp": "2024-06-12T10:30:00Z",
  "data": {
    "inboxId": "inb_123",
    "messageId": "msg_456",
    "subject": "Your verification code",
    "from": "noreply@example.com"
  }
}