Agent Webhooks
Wake workflows at the right moment instead of polling forever
Webhooks matter when a workflow needs to continue after a later user or system event. They should trigger fresh reads and deterministic continuation, not become a mysterious second source of truth.
Do not start with webhooks unless the workflow is truly asynchronous
Polling is simpler at the beginning. Webhooks become valuable once timing and continuity are product requirements.
Webhook Responsibilities
Treat events as triggers, not as the full business payload.
Trigger
The event tells the runtime that something changed and a workflow may need to resume.
- Use profile and assessment events to wake up the right jobs.
- Keep event routing explicit in the runtime.
- Do not put business logic in the delivery layer.
Re-fetch
After delivery, read fresh state from the canonical API surface before acting.
- Use webhooks to decide when to fetch, not what to trust blindly.
- Re-read context or a narrower endpoint before taking action.
- Keep delivery idempotent so duplicates are harmless.
Operations
Subscriptions need visibility, ownership, and cleanup.
- Track which workflow owns which webhook URL.
- Audit subscriptions outside the model loop.
- Delete stale subscriptions when a workflow is retired.
Use webhooks for continuation, not for basic reads
A webhook is most useful when the agent needs to continue work after some later event. It is usually unnecessary for simple read-only flows.
- Keep early integrations on direct reads until the event model is proven.
- Use webhooks when user progress or system changes need timed follow-up.
- Prefer explicit continuation flows over hidden background behavior.
Always pair delivery with a fresh contract read
The event payload should usually wake the workflow up, then the runtime should fetch canonical state before making a user-facing decision.
- Use the event to route the workflow, not to replace the data layer.
- Keep idempotency visible in runtime code and logs.
- Store enough metadata to debug duplicate or delayed delivery.
Webhook Comparison
Use event-driven continuation only where it clearly beats direct polling.
| Pattern | Best for | Avoid when |
|---|---|---|
| Direct reads | Simple request-response flows and first integrations. | The workflow must resume after later external events. |
| Polling | Short-lived interim checks while proving an event model. | The workflow becomes wasteful or time-sensitive. |
| Webhooks | Long-running workflows that need deterministic wake-up behavior. | You still have no clear event ownership or re-fetch plan. |
Decision Matrix
Use these rules to decide when a webhook-based design is the right next step.
Situation
The workflow can finish in one interaction
Action
Stay on direct reads.
Why
Adding event infrastructure would add cost without improving outcomes.
Situation
The workflow needs to react to later user progress
Action
Create a webhook subscription and re-fetch state on delivery.
Why
It is the cleanest way to resume with fresh data.
Situation
Delivery duplicates or delays occur
Action
Keep continuation idempotent and log every delivery attempt.
Why
Event systems are reliable when duplication is safe, not when it is impossible.
Webhook lifecycle examples
Create subscriptions explicitly, then list or inspect them from runtime tooling.
curl -X POST "https://api.profileclaw.com/api/v1/webhooks" -H "Authorization: Bearer $PROFILECLAW_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://example.com/profileclaw/webhooks","events":["profile.updated","assessment.completed"]}'curl "https://api.profileclaw.com/api/v1/webhooks" -H "Authorization: Bearer $PROFILECLAW_API_KEY"Next surfaces
Once the event model is clear, validate the exact contract and failure branches too.