API Reference: Webhooks
Complete reference for the Webhooks API including endpoints, event types, payload schemas, and examples.
Authentication
All webhook endpoints require a valid API key passed in the
Authorization header as Bearer <token>.Webhook Delivery
Webhooks are delivered with at-least-once semantics. Your endpoint must be idempotent and respond with a 2xx status code.
POST
/api/v1/webhooks/endpointsRegister a new webhook endpoint to receive event notifications.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | Required | The HTTPS URL to deliver webhook events to. |
| events | string[] | Required | List of events to subscribe to. See Event Types below. |
| secret | string | Optional | Optional secret for HMAC-SHA256 signature verification. |
bash
curl -X POST https://agentinbox.in/api/v1/webhooks/endpoints \ -H "Authorization: Bearer $AgentInbox_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-app.com/webhooks/AgentInbox", "events": ["email.received", "otp.extracted"], "secret": "whsec_..." }'typescript
const endpoint = await client.webhooks.create({ url: "https://your-app.com/webhooks/AgentInbox", events: ["email.received", "otp.extracted"], secret: "whsec_...",}); console.log(endpoint.id); // "whp_123"python
endpoint = client.webhooks.create( url="https://your-app.com/webhooks/AgentInbox", events=["email.received", "otp.extracted"], secret="whsec_...",) print(endpoint.id) # "whp_123"Responses
HTTP 201
{ "id": "whp_123", "url": "https://your-app.com/webhooks/AgentInbox", "events": ["email.received", "otp.extracted"], "status": "active", "createdAt": "2024-06-12T10:00:00Z"}HTTP 400
{ "error": "Invalid request", "message": "url must be a valid HTTPS URL"}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 500
{ "error": "Internal server error", "message": "Failed to create webhook endpoint"}GET
/api/v1/webhooks/endpointsList all registered webhook endpoints.
bash
curl -s https://agentinbox.in/api/v1/webhooks/endpoints \ -H "Authorization: Bearer $AgentInbox_API_KEY"typescript
const endpoints = await client.webhooks.list();console.log(endpoints.data);python
endpoints = client.webhooks.list()print(endpoints.data)Responses
HTTP 200
{ "data": [ { "id": "whp_123", "url": "https://your-app.com/webhooks/AgentInbox", "events": ["email.received", "otp.extracted"], "status": "active", "createdAt": "2024-06-12T10:00:00Z" } ]}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 500
{ "error": "Internal server error", "message": "Failed to list webhook endpoints"}DELETE
/api/v1/webhooks/endpoints/{id}Delete a webhook endpoint. No further events will be delivered to this URL.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique webhook endpoint ID. |
bash
curl -X DELETE https://agentinbox.in/api/v1/webhooks/endpoints/whp_123 \ -H "Authorization: Bearer $AgentInbox_API_KEY"typescript
await client.webhooks.delete("whp_123");python
client.webhooks.delete("whp_123")Responses
HTTP 204
// No bodyHTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Webhook endpoint not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to delete webhook endpoint"}POST
/api/v1/webhooks/eventsTest a webhook by sending a test event to your endpoint. Useful for verifying your integration.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| endpointId | string | Required | The webhook endpoint ID to send the test event to. |
| event | string | Required | The event type to simulate. |
bash
curl -X POST https://agentinbox.in/api/v1/webhooks/events \ -H "Authorization: Bearer $AgentInbox_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "endpointId": "whp_123", "event": "email.received" }'typescript
await client.webhooks.test({ endpointId: "whp_123", event: "email.received",});python
client.webhooks.test(endpoint_id="whp_123", event="email.received")Responses
HTTP 200
{ "success": true, "delivered": true, "responseStatus": 200}HTTP 400
{ "error": "Invalid request", "message": "endpointId is required"}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Webhook endpoint not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to send test event"}POST
/api/v1/webhooks/endpoints/{id}/rotate-secretRotate the webhook signing secret. The old secret is invalidated immediately.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The webhook endpoint ID to rotate the secret for. |
bash
curl -X POST https://agentinbox.in/api/v1/webhooks/endpoints/whp_123/rotate-secret \ -H "Authorization: Bearer $AgentInbox_API_KEY"typescript
const secret = await client.webhooks.rotateSecret("whp_123");console.log(secret);python
secret = client.webhooks.rotate_secret("whp_123")print(secret)Responses
HTTP 200
{ "secret": "whsec_new_...", "updatedAt": "2024-06-12T10:00:00Z"}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Webhook endpoint not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to rotate secret"}Event Types
All webhook payloads share a common envelope with event-specific data.
Common Envelope
{ "event": "email.received", "timestamp": "2024-06-12T10:30:00Z", "data": { /* event-specific data */ }}email.received
email.received
{ "event": "email.received", "timestamp": "2024-06-12T10:30:00Z", "data": { "inboxId": "inb_123", "messageId": "msg_456", "subject": "Your verification code", "from": "noreply@example.com", "to": ["k3v9x2m4q7tz@agentinbox.in"], "receivedAt": "2024-06-12T10:30:00Z" }}otp.extracted
otp.extracted
{ "event": "otp.extracted", "timestamp": "2024-06-12T10:30:01Z", "data": { "inboxId": "inb_123", "messageId": "msg_456", "extractionId": "ext_789", "value": "123456", "confidence": 0.98 }}wait.completed
wait.completed
{ "event": "wait.completed", "timestamp": "2024-06-12T10:30:01Z", "data": { "inboxId": "inb_123", "waitId": "wait_789", "status": "completed", "result": { "type": "otp", "value": "123456", "confidence": 0.98 } }}Signature Verification
Verify webhook signatures using the secret you configured when creating the endpoint.
Signature Algorithm
signature = HMAC-SHA256(payload, secret)header = "x-AgentInbox-signature: " + signatureSecurity
Always verify webhook signatures before processing the payload. Unsigned or incorrectly signed payloads should be rejected.