Skip to content
Transyt Docs

Quickstart

This guide walks you through connecting your first webhook provider to Transyt and receiving events in your application.

1. Create a Provider Account

Section titled “1. Create a Provider Account”

Use the Admin API to register a provider account. For example, to set up Stripe:

Terminal window
curl -X POST https://ingest.transyt.com/admin/accounts \
  -H "X-Admin-Token: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "stripe",
    "account_slug": "my-app",
    "app_key": "my-app",
    "signing_secret_current": "whsec_...",
    "delivery_url": "https://my-app.com/webhooks/transyt",
    "delivery_secret": "my-delivery-secret"
  }'

This creates an account that:

  • Listens for Stripe webhooks at https://ingest.transyt.com/stripe/my-app
  • Verifies signatures using your Stripe webhook secret
  • Delivers events to your application at https://my-app.com/webhooks/transyt

2. Configure Your Provider

Section titled “2. Configure Your Provider”

In your Stripe Dashboard (or whichever provider you’re using), set the webhook URL to:

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

For our example: https://ingest.transyt.com/stripe/my-app

3. Receive Webhooks in Your App

Section titled “3. Receive Webhooks in Your App”

When Transyt delivers an event to your application, it sends a POST request with:

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "provider": "stripe",
  "account_slug": "my-app",
  "event_type": "charge.succeeded",
  "external_id": "evt_1234567890",
  "payload": {
    "id": "evt_1234567890",
    "type": "charge.succeeded",
    "data": { "...": "original Stripe payload" }
  }
}

Headers included:

  • X-Gateway-Signature — HMAC-SHA256 hex digest for verification
  • X-Gateway-Timestamp — Unix timestamp of the delivery

4. Verify the Signature

Section titled “4. Verify the Signature”

Always verify the X-Gateway-Signature header to ensure the request came from Transyt:

# Rails
timestamp = request.headers["X-Gateway-Timestamp"]
signature = request.headers["X-Gateway-Signature"]
expected = OpenSSL::HMAC.hexdigest(
  "SHA256",
  ENV.fetch("GATEWAY_DELIVERY_SECRET"),
  "#{timestamp}.#{request.raw_post}"
)
unless ActiveSupport::SecurityUtils.secure_compare(signature.to_s, expected)
  head :unauthorized
  return
end

See full examples for Rails and Laravel.

5. Test Your Setup

Section titled “5. Test Your Setup”

Trigger a test delivery to verify your endpoint is reachable:

Terminal window
curl -X POST https://ingest.transyt.com/admin/accounts/{account_id}/test-delivery \
  -H "X-Admin-Token: YOUR_ADMIN_TOKEN"

Next Steps

Section titled “Next Steps”