Webhooks
Receive real-time notifications when events occur in Agency OS AI.
Overview
Webhooks send HTTP POST requests to your endpoints when events occur, enabling:
- Real-time integrations with external systems
- Automated workflows and notifications
- Synchronization with other tools
Creating Webhooks
- Navigate to Agency OS → Settings → Webhooks
- Click Add Webhook
- Configure:
- Name - Descriptive name
- URL - Endpoint to receive POST
- Events - Select events to trigger
- Secret - For signature verification
- Click Save Webhook
Available Events
| Event | Description |
|---|---|
| client.created | New client added |
| client.updated | Client details changed |
| project.created | New project created |
| project.updated | Project details changed |
| project.completed | Project marked complete |
| task.created | New task added |
| task.updated | Task details changed |
| task.stage_changed | Task moved to new stage |
| invoice.created | New invoice created |
| invoice.sent | Invoice emailed to client |
| invoice.paid | Invoice payment received |
| ticket.created | New support ticket |
| ticket.reply | Ticket reply added |
| time_entry.created | New time entry logged |
Payload Format
Webhook payloads are JSON:
{
"event": "invoice.paid",
"timestamp": "2026-03-31T12:00:00Z",
"data": {
"id": 42,
"invoice_number": "INV-2026-0042",
"client_name": "Acme Corporation",
"amount": 1500.00,
"currency": "USD",
"paid_date": "2026-03-31"
}
}
Security
Verify webhook authenticity using the signature header:
Headers:
X-AOSAI-Signature: sha256={signature}
X-AOSAI-Timestamp: {timestamp}
Verification:
$payload = file_get_contents('php://input');
$secret = 'your_webhook_secret';
$expected = hash_hmac('sha256', $timestamp . $payload, $secret);
$valid = hash_equals($expected, $signature);
Response Handling
Your endpoint should:
- Return 200 OK within 30 seconds
- Process payload asynchronously if needed
- Implement idempotency using event IDs
Webhook Management
Manage webhooks in Agency OS → Settings → Webhooks:
- View Logs - See recent deliveries
- Retry Failed - Manually retry deliveries
- Test - Send test payload
- Disable - Pause webhook temporarily