
Webhook lifecycle steps: follow up in your own stack without leaving Rheo
Use profile-enriched JSON webhooks in Rheo Engage automations and broadcasts to sync lifecycle events to your CRM, data warehouse, or custom backends.
Email and push cover most lifecycle needs. Some teams must write to systems Rheo does not replace: Salesforce opportunities, internal admin tools, Slack war rooms, or a Rust microservice that grants promo credits. Copy-pasting user IDs from the dashboard does not scale.
Rheo Engage supports webhook steps in automations (and webhook-style actions alongside broadcasts where configured) that POST profile-enriched JSON to endpoints you control. This post covers payload shape, security, retries, idempotency, and patterns that keep Rheo the journey orchestrator while your stack owns side effects.
When to use webhooks vs native channels
| Use webhook when | Use email/push when |
|---|---|
| CRM must create a task for sales | User-facing message required |
| Warehouse needs real-time row | No internal system in path |
| Custom credit / entitlement logic | Standard lifecycle copy |
| Slack alert for high-value churn | Scale to millions without your servers |
Webhooks are server-to-server. They are not a replacement for user notification unless your product reads from the CRM inbox.
Where webhooks live in Engage
Automations: add a Webhook step after waits or branches: e.g. trial started → wait 1h → webhook to enrichment service → email.
Broadcasts: optional companion webhook to log “campaign X sent” to your data lake for users in audience (pattern varies by workspace; automations are the primary graph for multi-step).
Profile enrichment: payloads include customer traits and recent context so receivers do not call back to Rheo for every field.
Payload design (conceptual)
Exact schema follows your workspace API version; plan for:
| Field group | Examples |
|---|---|
| Event metadata | event_type, automation_id, step_id, occurred_at |
| Customer identity | Rheo customer ID, external IDs you set |
| Traits | email, plan, marketing_email_consent, custom |
| Recent product context | Last flow ID, variant, funnel step |
| Billing snapshots | Trial end, subscription status from integrations |
Keep payloads minimal for PII: send what the endpoint needs, not entire history.
Example shape (illustrative):
{
"type": "engage.webhook_step",
"sentAt": "2026-11-05T12:00:00.000Z",
"automationId": "auto_trial_nurture",
"stepId": "wh_sync_crm",
"customer": {
"id": "cus_abc123",
"externalId": "user_9988",
"traits": {
"email": "user@example.com",
"trialEndsAt": "2026-11-12T00:00:00.000Z",
"platform": "ios"
}
},
"context": {
"flowId": "flow_onboarding_v14",
"variantId": "var_b"
}
}
Version your payload with type or schema_version so receivers evolve safely.
Security
| Control | Recommendation |
|---|---|
| HTTPS only | Reject plain HTTP endpoints in production |
| Authentication | Shared secret header, HMAC signature, or mTLS |
| IP allowlist | If Rheo publishes egress ranges |
| PII | Encrypt at rest on your side; minimize fields |
| Replay | Include event_id; reject duplicates |
Verify signatures in your handler before parsing body. Rotate secrets without downtime using dual-secret window.
Reliability: retries and dead letters
Webhooks fail: timeouts, 503s, bad deploys. Engage queues delivery with retries and eventual dead-letter state (see Engage worker ops in platform docs).
Your endpoint should:
- Return 2xx only after durable write (or queue to internal bus).
- Return 4xx for bad payload (fix forward).
- Return 5xx for transient errors (trigger retry).
- Complete within timeout budget (optimize DB writes).
Idempotency: use event_id or (customer_id, step_id, sentAt) as unique key in your store.
Idempotent handler sketch (Node)
export const handleRheoWebhook = async (req: Request) => {
verifySignature(req);
const body = await req.json();
const id = body.eventId ?? `${body.customer.id}:${body.stepId}:${body.sentAt}`;
const inserted = await db.engageEvents.insertIfNotExists(id, body);
if (!inserted) return new Response('OK', { status: 200 });
await crm.upsertLead(body.customer);
return new Response('OK', { status: 200 });
};
Patterns that work
CRM task on high-intent stall
Automation: paywall_viewed + no trial_started 24h → webhook creates SDR task with traits → optional email in parallel.
Slack for churn
Cancel event → webhook to #churn with MRR estimate trait from billing sync.
Warehouse streaming
Webhook → your API → Kafka → Snowflake. Cheaper than polling Rheo for batch exports for operational triggers.
Custom promo credits
Branch: loyal user segment → webhook to ledger service → email confirms credit.
Do not implement billing charges in webhook handlers: keep RevenueCat/Stripe authoritative.
Webhooks + email in one journey
Order matters:
| Order | Rationale |
|---|---|
| Webhook then email | CRM row exists before user clicks support link |
| Email then webhook | User notified even if your API is down: monitor DLQ |
For compliance, webhooks that store PII need the same consent basis as marketing email when used for promotional follow-up in external tools.
Testing
| Stage | Approach |
|---|---|
| Local | ngrok or Cloudflare tunnel + staging automation |
| Staging | Dedicated endpoint with fixture assertions |
| Production | Canary automation on internal profiles |
Log request bodies redacted in CI; never commit secrets.
Observability
Monitor:
- Success rate by automation step
- p95 latency your endpoint
- DLQ depth (replay after fix)
- Divergence: webhook succeeded but user says no email: check parallel steps
Admin Engage worker views expose queue health for platform operators.
Compare to exporting segments
| Approach | Best for |
|---|---|
| Nightly segment CSV | Marketing-only batch |
| Webhook per user event | Real-time ops and CRM |
| Rheo native email/push | User communication without your servers |
Broadcast companion webhooks
For large broadcasts, some teams POST a summary event per batch (campaign_sent) to their lake, while automations emit per-user events. Choose based on downstream cost:
| Pattern | Volume | Downstream load |
|---|---|---|
| Per-user webhook on broadcast | High | Heavy; prefer segment export API if batch |
| Per-user on automation entry | Medium | Justified for CRM tasks |
| Aggregate only | Low | Cheap; loses per-user CRM timing |
If your handler cannot sustain broadcast fan-out, throttle with an internal queue: never drop events silently.
Failure runbook (template)
- Check Engage worker DLQ depth and last error message.
- Verify endpoint TLS cert and DNS.
- Roll back deploying service if 5xx spike correlates with release.
- Replay dead-lettered events after fix (idempotent store required).
- Post-mortem: was timeout too aggressive for cold-start Lambda?
Keep runbook linked from the automation description field so on-call does not grep Slack history at 2 a.m.
Related posts
- Lifecycle email and push from in-app events
- Event-triggered win-back with webhooks
- From funnel drop-off to Engage campaign
- Analyze → segment → convert → engage
Bottom line
Webhooks let Rheo Engage orchestrate lifecycle timing while your stack owns CRM, credits, and alerts without abandoning the unified profile. Design small signed payloads, idempotent handlers, and retries you can replay. The journey stays in Rheo; the side effects stay where your engineers already operate.