​

Consume journey webhook node calls

​

1. Journey webhook node vs. organization event webhook

​

2. Configuring the node

• webhookUrl (required): the HTTPS endpoint to call. The URL is validated when the journey is saved: it must be https, and URLs that point at localhost, private ranges, link-local ranges, or cloud-metadata addresses are rejected with a validation error naming the node.
• method (optional, default POST): one of GET, POST, PUT, PATCH, DELETE. A method outside the allowlist is rejected at save.

1. Save time. The URL string is validated when the journey definition is saved, so an obviously unsafe URL never persists.
2. Send time. When a contact reaches the node, the URL is validated again, this time against the addresses the hostname actually resolves to, immediately before the call is made. This closes the gap where a hostname that was public at save time later resolves to an internal address.

​

3. The payload contract

{
  "campaign_id": "cmp_9f2e1a",
  "journey_name": "Welcome series — new signups",
  "node_id": "n_sync_crm",
  "contact_id": "ctc_51d3b7",
  "recipient": "+14155550142",
  "timestamp": "2026-11-04T09:14:07.381Z"
}

• journey_name can be empty. A journey whose campaign has neither a name nor a title sends "". Never branch on journey_name alone; pair it with campaign_id, or treat the empty string as an explicit case.
• The shape is fixed. The six fields above are the whole payload. If you need more contact context, fetch it by contact_id from the API rather than expecting extra fields to appear.

​

4. Worked consumer: one endpoint, three journeys

// express >= 4, body parsed with express.json()
const WINDOW_MS = 5 * 60 * 1000; // accept deliveries up to 5 minutes old
const seen = new Set(); // in production: a durable store with TTL, not a Set

app.post("/orbit/journey-webhook", express.json(), (req, res) => {
  const {
    campaign_id: campaignId,
    journey_name: journeyName,
    node_id: nodeId,
    contact_id: contactId,
    recipient,
    timestamp,
  } = req.body ?? {};

  // 1. Respond fast, unconditionally, once input is parsed.
  res.status(200).json({ ok: true });

  // 2. Everything else happens off the request path.
  setImmediate(() => {
    // Reject stale or unparsable timestamps (replays, redeliveries from
    // before a rename, clock issues on your side).
    const age = Date.now() - Date.parse(timestamp);
    if (!Number.isFinite(age) || age < 0 || age > WINDOW_MS) {
      console.warn("stale journey webhook", { campaignId, nodeId, timestamp });
      return;
    }

    // Dedupe. A contact can traverse the same node twice (loops, waits),
    // so (campaign, node, contact) is the at-most-once-processing key.
    const key = `${campaignId}:${nodeId}:${contactId}`;
    if (seen.has(key)) return;
    seen.add(key);

    // Branch on journey + node.
    if (journeyName === "Welcome series — new signups" && nodeId === "n_sync_crm") {
      queue.enqueue("crm.sync", { contactId, recipient });
    } else if (journeyName === "Cart recovery" && nodeId === "n_notify_orders") {
      queue.enqueue("orders.recover", { contactId });
    } else if (journeyName === "Winback" && nodeId === "n_alert_support") {
      queue.enqueue("support.winback", { contactId, recipient });
    } else {
      // Unknown journey or node: log, don't crash. New journeys can go
      // live while this endpoint is running.
      console.warn("unrouted journey webhook", { journeyName, nodeId });
    }
  });
});

• Respond 2xx inside the 10-second budget (below) and queue the real work. Any processing you do before responding counts against Orbit’s timeout.
• Deduplicate on (campaign_id, node_id, contact_id) because re-traversal is legal.
• Branch defensively: an endpoint that serves several journeys will eventually receive a journey it does not know about yet.
• Verify the timestamp window so a replayed or very old delivery cannot re-trigger processing.

​

5. Semantics you must plan for

• No retries and no dead-letter queue. If the call fails, times out, or is skipped, Orbit logs it server-side and the contact continues down the journey as if the call succeeded. There is no second attempt and no queue to drain later. If a hand-off is business-critical, make your endpoint durable on the first attempt (accept, persist, process asynchronously) and monitor your own inbound logs for gaps.
• A 10-second response budget. Each call carries a 10-second timeout. An endpoint that responds in 10.001 seconds is a failed call, identical to a 5xx from the node’s point of view.
• Pausing aborts in-flight calls. Pausing the campaign aborts webhook calls that are in flight at that moment. If you were mid-burst when an operator paused the journey, expect some contacts’ calls to be aborted rather than delivered; the journey resumes from where it paused, and those contacts continue (their aborted calls are not retried).
• SSRF-rejected URLs are skipped silently from your side. A URL that fails the send-time safety validation, is http rather than https, or resolves to a private, link-local, or metadata address is never dialed. Your endpoint sees nothing; the skip is visible only in Orbit’s server-side logs. If deliveries for one journey stop entirely while other journeys keep arriving, check that the journey’s URL is still public and still https.
• Duplicates are normal. A contact that re-enters a node, after a wait or a loop, produces another delivery with the same (campaign_id, node_id, contact_id) and a new timestamp. Design for at-least-once arrival with consumer-side dedup, not exactly-once delivery.
• Journey webhook calls are not signed. The payload carries no signature header. If you need to authenticate the sender, gate at the network layer (allowlist Orbit’s egress ranges, or put a shared secret in the URL you configure on the node), or use organization event webhooks, which support signature verification, for anything that must be provably from Orbit. See Verifying webhook signatures.

​

6. Testing loop before launch

1. Dry-run the journey in the simulator first. The simulator walks test contacts through the graph and shows per-node behavior, including webhook nodes, before launch. See Campaign journey simulation and inspection.
2. Point the node at the webhook tester or a sandbox sink. Capture the exact body your endpoint will receive, and assert your parser accepts all six fields, including an empty journey_name. See Webhook tester.
3. Enroll a single test contact in the sandbox and watch the delivery arrive end to end, including your dedup and timestamp-window paths (send the same contact through twice on purpose).
4. Load-test your response time. Your p99 must sit comfortably inside the 10-second budget with headroom, because anything above it is a silently failed hand-off.

​

7. Troubleshooting

​

Related

• Build, simulate, and launch a campaign journey: the canvas, node vocabulary, and save-time validation errors.
• Webhook consumer production checklist: the general hardening list for any endpoint that receives Orbit webhooks.
• Webhook payload cookbook: payload-handling patterns across Orbit’s webhook surfaces.
• Campaign journey simulation and inspection: dry-run a journey, webhook nodes included, before launch.