Skip to main content

Event-driven integrations

Event-driven integrations respond to things that happen in third-party systems - a new record is created, a payment completes, a file is uploaded. Rather than polling for changes, the external system pushes events to your integration via webhooks.

Webhook lifecycle management​

Use lifecycle handlers in your custom trigger to register and deregister webhook subscriptions automatically:

  • onInstanceDeploy - register the webhook subscription and persist the returned webhookId and signingSecret in Cross-Flow State.
  • onInstanceDelete - unsubscribe and clean up the webhook when the instance is removed.

If webhook registration logic lives outside a custom trigger, use a Management Trigger flow as an alternative.

Security​

Always verify webhook signatures using HMAC on every incoming request. Many built-in components handle this automatically; for custom triggers, implement verification manually.

Ordering and deduplication​

For workflows where event order matters - financial transactions, inventory updates - enable FIFO queues on your flow. FIFO queues process events one at a time in order and support message deduplication using a deduplication ID (such as a webhook event ID header) to prevent processing duplicates within a 10-minute window.

Batched payloads​

Many systems deliver arrays of events in a single webhook request. Loop over each event individually, validate and deduplicate per eventId, and dispatch to sub-flows based on event type as needed. Isolate failures so one bad event doesn't fail the entire batch.

Error handling​

Use retry steps with exponential backoff for transient failures. After a defined number of attempts, escalate to a dead-letter flow or alert and record minimal context (such as eventId) in Flow State for targeted reprocessing.

Best practices​

  • Keep handlers fast. Validate the request, deduplicate the event, then hand off to async processing. Avoid heavy logic in the trigger itself.
  • Make handlers idempotent. Design flows to be safe to retry. Deduplicate using stable event IDs.
  • Configure triggers for reuse. Expose inputs for object/topic selection and event type filtering with sensible defaults, so the same trigger can be reused across customers.