Buffy's behavior engine sits at the center of an activity lifecycle: a habit is created, a reminder is dispatched, a response is logged, a pattern is updated. Webhooks let you tap into that lifecycle from your own app — trigger Buffy when something happens in your system, or react in your system when Buffy logs a behavior. This guide covers both directions, the full outbound setup sequence, the exact payload shape, and practical automation patterns.
What are Buffy webhooks?
- Buffy webhooks: HTTP integration points that connect Buffy's behavior engine to external systems in real time — either receiving events from your app (inbound) or sending events to your app (outbound).
- What you'll learn in this guide:
- The two webhook directions and when to use each
- Step-by-step setup for outbound webhooks
- The exact payload shape Buffy sends
- Common automation patterns
Two directions: inbound and outbound
Inbound webhooks (your system → Buffy)
Your app sends a POST request to Buffy's inbound webhook endpoint when something happens in your system that should affect the behavior engine — without requiring the user to interact with Buffy directly.
Common triggers:
- A user completes an onboarding step → mark the associated task done in Buffy
- A user logs a workout in your fitness app → log the "workout" habit activity
- A user reaches a milestone in your product → activate a Buffy routine
Endpoint: POST https://api.buffyai.org/v1/webhooks/inbound
Payload:
{
"event": "activity.completed",
"activity_id": "act_xyz789",
"user_id": "usr_abc123",
"timestamp": "2026-03-28T08:12:44Z"
}
Include your API key in the Authorization: Bearer <token> header. The behavior core processes the event synchronously, updates activity state, and reflects the change across all of the user's channels.
Outbound webhooks (Buffy → your system)
Buffy POSTs to a URL you register whenever a behavior event occurs. You subscribe to the event types you care about.
Available event types:
activity.completed— user marked a habit or task doneactivity.skipped— user explicitly skipped an activityactivity.snoozed— user snoozed with a durationreminder.sent— Buffy dispatched a nudge to a channelroutine.partial— routine completed with at least one step skipped
Register your endpoint in Settings → Developer → Webhooks.
Setting up outbound webhooks
- Go to Settings → Developer → Webhooks in your Buffy account at www.buffyai.org.
- Click Add endpoint and enter your HTTPS URL.
- Select which event types to subscribe to (
activity.completed,activity.skipped,activity.snoozed,reminder.sent,routine.partial). - Copy your webhook signing secret — Buffy signs every payload with HMAC-SHA256.
- In your app, verify the
X-Buffy-Signatureheader before processing any payload. Reject requests where the signature does not match. - Respond with HTTP
200within 5 seconds. Buffy retries 3 times with exponential backoff on any non-200 response or timeout.
Payload shape
Here is a concrete example of what an activity.completed event looks like when Buffy POSTs to your endpoint:
{
"event": "activity.completed",
"timestamp": "2026-03-28T08:12:44Z",
"user_id": "usr_abc123",
"activity": {
"id": "act_xyz789",
"type": "habit",
"name": "Drink water",
"channel": "telegram"
}
}
All outbound payloads follow this envelope shape: a top-level event string, an ISO 8601 timestamp, a user_id, and an object for the relevant entity (activity, reminder, or routine). The entity object shape varies by event type — consult the API reference for the full field list per event.
Common automation patterns
Zapier / Make integration
Use Buffy's outbound activity.completed event as a Zapier trigger. From there you can update a Notion database with habit completions, log rows to an Airtable base for reporting, or send a daily Slack summary of all activities completed — no server required.
Fitness app sync
Fire an inbound webhook from your fitness app when a user logs a workout. The webhook marks the "workout" habit done in Buffy immediately — the user never has to reply in Telegram, and their streak updates automatically.
Onboarding integration
When a user completes your product's onboarding flow, fire an inbound webhook to create their initial habit set in Buffy. This pairs the moment of intent (onboarding) with the activation of the behavior engine, without requiring the user to set up Buffy separately.
Analytics pipeline
Subscribe to all activity.* events and stream them to your analytics warehouse. This lets you track behavioral engagement — completion rates, skip patterns, streak lengths — alongside product usage data in the same pipeline.
Rate limits and reliability
Buffy processes inbound webhooks synchronously up to 100 requests per minute per user. For high-volume integrations (bulk backfills, batch completions), use the Activities API (POST /v1/activities/bulk) instead of individual webhook calls.
Outbound webhooks are best-effort with 3 retries. For guaranteed delivery or historical access, poll the event log via GET /v1/events, which retains a full, ordered history of behavior events and supports cursor-based pagination.