Core Concepts

Providers

A provider is a third-party service that sends webhooks to Transyt. Each provider has its own signature verification algorithm, event type format, and external ID scheme.

Supported providers: stripe, signalwire, twilio, lob, ses, mailgun, resend, ramp, linear, authorize-net, crisp, whatconverts, beds24, and generic.

Provider Accounts

A provider account represents a specific connection between a provider and your organization. For example, you might have two Stripe accounts — one for production and one for staging.

Each account has:

• provider — Which provider this account belongs to (e.g., stripe)
• account_slug — A unique identifier within the provider (e.g., my-app-prod)
• app_key — Groups accounts under a logical application
• signing_secret_current — The active secret for signature verification
• signing_secret_previous — The previous secret, used during secret rotation
• delivery_url — Where to push events (optional)
• delivery_secret — Secret used to sign outbound deliveries

The webhook ingestion URL for an account is:

https://ingest.transyt.com/{provider}/{account_slug}

Events

An event is a single webhook received by Transyt. Each event is identified by a provider-specific external ID and deduplicated at the database level.

Event Statuses

Status	Description
received	Persisted to the database, awaiting processing
enqueued	Picked up by a consumer, processing job created
processed	Successfully processed by the consumer
failed	Processing failed, may be retried
dead	Exhausted all retries, requires manual intervention
rejected	Failed signature verification (stored for debugging)

Event Type Normalization

Transyt normalizes provider-specific event types into a consistent format. For example:

Provider Event	Normalized Event
charge.succeeded (Stripe)	payment.completed
email.delivered (Mailgun)	email.delivered
message:send (Crisp)	chat.message

The original event type is always preserved in the event_type_raw field.

Delivery

Delivery is the process of sending an event from Transyt to your application. There are two delivery modes:

Push Delivery (Recommended)

Transyt POSTs events directly to your delivery_url. Each delivery includes:

• The full event payload in the Transyt envelope format
• X-Gateway-Signature and X-Gateway-Timestamp headers for verification
• Automatic retries with exponential backoff

Delivery Statuses

Status	Description
pending	Not yet attempted or awaiting retry
delivered	Successfully delivered (2xx response)
failed	Exhausted all retries

Delivery URL Cascading

Delivery URLs can be set at two levels:

1. Account-level delivery_url — Takes precedence
2. Project-level project_delivery_url — Fallback if account has none

The same cascading applies to delivery secrets.

Destinations

Destinations are additional notification targets triggered after primary delivery succeeds or fails. They enable fan-out to multiple systems.

Destination types:

• Webhook — POST to any URL
• Email — Send via Amazon SES
• Slack — Send to a Slack channel
• Discord — Send to a Discord channel

Each destination can have a condition expression that determines when it fires.

Deduplication

Transyt deduplicates events at the database level using a unique constraint on (provider_account_id, external_id). When a provider retries a webhook that’s already been received, the duplicate INSERT is silently skipped via ON CONFLICT DO NOTHING.

This provides atomic, race-condition-free deduplication without application-level locking.