Rheo
Engage automation with a webhook step sending enriched customer JSON to an external API
Engineering

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 whenUse email/push when
CRM must create a task for salesUser-facing message required
Warehouse needs real-time rowNo internal system in path
Custom credit / entitlement logicStandard lifecycle copy
Slack alert for high-value churnScale 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 groupExamples
Event metadataevent_type, automation_id, step_id, occurred_at
Customer identityRheo customer ID, external IDs you set
Traitsemail, plan, marketing_email_consent, custom
Recent product contextLast flow ID, variant, funnel step
Billing snapshotsTrial 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

ControlRecommendation
HTTPS onlyReject plain HTTP endpoints in production
AuthenticationShared secret header, HMAC signature, or mTLS
IP allowlistIf Rheo publishes egress ranges
PIIEncrypt at rest on your side; minimize fields
ReplayInclude 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:

  1. Return 2xx only after durable write (or queue to internal bus).
  2. Return 4xx for bad payload (fix forward).
  3. Return 5xx for transient errors (trigger retry).
  4. 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:

OrderRationale
Webhook then emailCRM row exists before user clicks support link
Email then webhookUser 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

StageApproach
Localngrok or Cloudflare tunnel + staging automation
StagingDedicated endpoint with fixture assertions
ProductionCanary 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

ApproachBest for
Nightly segment CSVMarketing-only batch
Webhook per user eventReal-time ops and CRM
Rheo native email/pushUser 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:

PatternVolumeDownstream load
Per-user webhook on broadcastHighHeavy; prefer segment export API if batch
Per-user on automation entryMediumJustified for CRM tasks
Aggregate onlyLowCheap; 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)

  1. Check Engage worker DLQ depth and last error message.
  2. Verify endpoint TLS cert and DNS.
  3. Roll back deploying service if 5xx spike correlates with release.
  4. Replay dead-lettered events after fix (idempotent store required).
  5. 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.

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.

Start for free