Webhooks

Webhooks enable real-time notifications when events occur in MeetLoyd. Instead of polling the API, receive HTTP callbacks when agents complete tasks, conversations end, or workflows finish.

Why Webhooks?

• Real-time updates -- know immediately when events happen
• Efficient -- no polling required
• Reliable -- automatic retries on failure
• Secure -- signature verification on every delivery

Available Events

Conversation Events

Event	Description
conversation.created	New conversation started
conversation.message	New message in conversation
conversation.completed	Conversation ended
conversation.error	Conversation error occurred

Task Events

Event	Description
task.created	Task created
task.started	Task execution began
task.completed	Task finished successfully
task.failed	Task failed
task.cancelled	Task was cancelled

Workflow Events

Event	Description
workflow.started	Workflow execution began
workflow.completed	Workflow finished successfully
workflow.failed	Workflow failed
workflow.human_task	Human task awaiting response

Agent Events

Event	Description
agent.created	Agent created
agent.updated	Agent configuration changed
agent.deleted	Agent deleted
agent.tool_called	Agent called a tool

Retry Policy

Failed deliveries are retried automatically:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	8 hours

After 6 failed attempts, the webhook is marked as failed. Failures include HTTP status >= 400, connection timeout (30 seconds), and network errors.

Signature Verification

All webhook requests include X-MeetLoyd-Signature and X-MeetLoyd-Timestamp headers. Always verify these to prevent spoofing. The signature is an HMAC-SHA256 of {timestamp}.{payload} using your webhook secret.

Always Verify

Never process a webhook without verifying the signature first. This prevents spoofed requests from being processed.

---

Next: Explore Tasks for background job execution.