Event integration patterns¶
Status: Current | Last reviewed: 2026-07-07
You have three shapes available for event-driven integration: webhooks, brokers, and Salesforce Pub/Sub. They have different durability, latency, and operational characteristics. Pick deliberately.
Comparison¶
| Trait | Webhook | Broker | Salesforce Pub/Sub |
|---|---|---|---|
| Direction | Caller → TrueServe | Queue → TrueServe (TrueServe pulls) | Salesforce → TrueServe (TrueServe pulls via gRPC) |
| Latency | Single-digit ms ack | 10–100 ms typical | Single-digit ms |
| Durability | Caller-managed retries | Queue-managed retries | Replay-id based; SF retains 72h |
| At-least-once? | Caller retry only; generic event ingest assigns a new id per accepted request | Yes natively | Yes, via replay ID |
| Failure isolation | Per-request | Per-message DLQ | Per-message; channel cursor advances on success |
| Setup work | Low | Medium (provision queue + IAM) | Low if SF already connected |
Webhook¶
Best for partner systems and any source you don't operate the queue for. The caller bears the durability burden — they retry on 5xx, you dedupe.
Idempotency¶
The generic event endpoint assigns a new event id for each accepted request. Treat 202 Accepted as the handoff point and retry only when the caller did not receive a response. If your source can retry after an unknown result and duplicate processing would be harmful, use a broker or provider adapter with a stable upstream event id.
Failure handling¶
| Scenario | What happens |
|---|---|
| Caller gets no response and retries | May create a second event if the first request was accepted before the connection failed |
| Caller hits 4xx | Caller's bug; fix the request and resend |
| Workflow itself fails after 202 | Failure recorded against the run; caller can't see it |
The 202 means "ingested," not "processed." Catch workflow-level failures via the workflow's own notification node.
Broker¶
Best for high-volume async ingest where "we cannot afford to drop one of these" matters more than latency. RabbitMQ, AWS SQS, GCP Pub/Sub all supported.
Wire-up¶
- Provision the queue in your cloud account / on-prem RabbitMQ.
- Add it as an integration in TrueServe (under Integrations → Brokers). The integration form asks for connection details and IAM context.
- In the workflow trigger, pick the broker as the source.
The platform's broker consumer pulls messages, dispatches into the workflow runner, and acks on success. Failed messages go to the configured DLQ — the platform never silently drops broker traffic.
When to prefer over webhook¶
- Burst volume > 100 events/sec sustained.
- Source can't easily implement retry-with-idempotency-key.
- You need DLQ semantics (auditing what failed and why).
- Your operational model already includes the queue.
Salesforce Pub/Sub¶
Best for real-time CRM reactivity. The platform opens a gRPC stream against Salesforce's Pub/Sub API and consumes events as they're published.
Replay IDs¶
Salesforce assigns each event a monotonic replay ID. The platform persists the last-acked replay ID per channel per workflow. If the platform restarts, it resumes from the last acked ID — events published during downtime are replayed.
Salesforce retains replayable events for 72 hours. Longer downtime means lost events; alarms should fire well before that window.
Channel auth¶
The OAuth grant on the connected Salesforce integration carries the right scopes. If a channel name is rejected ("not subscribable"), check that the connected user has CDC or platform-event subscribe permission for that object.
Picking the pattern¶
| If you... | Use |
|---|---|
| Are a partner integrating a third-party SaaS | Webhook |
| Run high-throughput async pipelines already | Broker |
| Need to react to Salesforce changes | Salesforce Pub/Sub |
| Already know the workflow id and need request/response semantics | Direct workflow execution |