YOURAUTOMATION.AI
SYS: OPERATIONALUPTIME: 99.8%

API REFERENCE

Webhooks API

Webhooks notify your application when events occur in your agent infrastructure. Receive real-time updates for executions, errors, and system events.

The Webhook Object

Webhook object
{ "id": "wh_abc123def456", "url": "https://api.example.com/webhooks/ya-events", "events": ["execution.completed", "execution.failed"], "agentId": "agt_abc123", "secret": "whsec_abc123...", "status": "active", "createdAt": "2026-03-15T10:30:00Z" }

Available Events

EventDescription
execution.startedAgent execution has begun
execution.completedAgent execution finished successfully
execution.failedAgent execution encountered an error
execution.cancelledAgent execution was cancelled
tool.calledAgent called a tool during execution
tool.errorA tool call failed
agent.createdA new agent was created
agent.updatedAn agent was modified
agent.deletedAn agent was deleted
key.createdA new API key was created
key.revokedAn API key was revoked

Create a Webhook

POST /v1/webhooks

Request
{ "url": "https://api.example.com/webhooks/ya-events", "events": ["execution.completed", "execution.failed", "tool.error"], "agentId": "agt_abc123" }
Response (201)
{ "id": "wh_abc123def456", "url": "https://api.example.com/webhooks/ya-events", "events": ["execution.completed", "execution.failed", "tool.error"], "agentId": "agt_abc123", "secret": "whsec_abc123def456ghi789...", "status": "active", "createdAt": "2026-03-15T10:30:00Z" }

Webhook Payload

Your endpoint receives POST requests with the following structure:

Delivery payload
POST https://api.example.com/webhooks/ya-events Content-Type: application/json X-YA-Webhook-Id: wh_abc123 X-YA-Webhook-Signature: sha256=abc123... X-YA-Webhook-Timestamp: 1710547200 { "id": "evt_abc123", "type": "execution.completed", "data": { "executionId": "exec_def456", "agentId": "agt_ghi789", "status": "completed", "output": "I'd be happy to help...", "usage": { "totalTokens": 231 }, "duration": 1234 }, "createdAt": "2026-03-15T10:30:00Z" }

Signature Verification

Always verify webhook signatures to ensure requests are from YourAutomation:

Node.js verification
import crypto from "crypto"; function verifySignature(payload: string, signature: string, secret: string) { const expected = crypto .createHmac("sha256", secret) .update(payload) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(signature.replace("sha256=", "")), Buffer.from(expected) ); }

Update a Webhook

PATCH /v1/webhooks/:id

Request
{ "events": ["execution.completed", "execution.failed"], "status": "paused" }

Delete a Webhook

DELETE /v1/webhooks/:id

Response (200)
{ "id": "wh_abc123def456", "deleted": true }

Retry Policy

Failed deliveries (non-2xx responses) are retried up to 5 times with exponential backoff: 1s, 5s, 30s, 2min, 10min. After all retries fail, the webhook is paused and you receive an email notification. Reactivate paused webhooks from the dashboard or via the API.