To start receiving messages (webhooks) from Straddle, you’ll first need to configure your endpoints in the Straddle dashboard.

​
Getting Started

  1. Navigate to the “Webhooks” section in your “Developers” menu.

  2. Add an endpoint by providing a URL that you control and selecting the event types you want to listen to.

​
Svix x Straddle

We’ve partnered with Svix to enable instant testing and debugging of Straddle webhooks.

  • No URL yet? If your service isn’t ready or you don’t have a URL, click the “Use Svix Play” button to generate a unique test URL.

  • You’ll be able to view and inspect all webhooks sent to your Svix Play URL, making it easy to get started before your own endpoint is live.

When configuring your endpoint, make sure to review the Event Catalog for full descriptions of each event type and the fields they include.

If you don’t specify any event types, your endpoint will receive all events, which can be useful for testing. However, once you’re ready for production, we recommend restricting the event types to those you actually need.

​
Integration Tips

​
Use the Built-in Svix Debugger

When first starting out, we recommend using the built-in Svix debugger. This allows you to trigger generated (fake) event bodies to your specified URL on command. It’s perfect for:

  • Quickly understanding the JSON structure of events.

  • Iterating on your handling logic before going live.

Since these events are fake, all IDs and URLs within them are inaccessible and do not map to real resources.

​
Local Development with ngrok

When you’re ready to move on to local development, we recommend using a tunneling tool like ngrok. Ngrok makes it possible for Straddle to reach your locally running web server without you needing to deploy it. This setup allows you to develop and test your webhook handling logic in real-time.

​
Receiving Webhooks

To receive webhooks from Straddle:

  • Create a new endpoint on your web server that accepts POST requests with Content-Type: application/json.

  • Ensure this endpoint is accessible by Straddle (avoid firewalls or IP restrictions that would block requests).

  • When Straddle sends you a webhook, respond with a 2xx status code to confirm receipt. Any other status code (or lack thereof) will be considered a failure, and Straddle will attempt to retry delivery.

If your webhook endpoint does additional processing, you can return 2xx immediately and then perform the logic afterward. This prevents unnecessary retries caused by slow or complex processing steps.

Any information you return in the response will be recorded and visible in the Straddle Dashboard logs. Although Straddle won’t process this data, it can be useful for debugging. We recommend returning a concise JSON object with any helpful info.

Straddle sends webhook events as soon as they become available. While typically fast, real-time guarantees are not provided, and occasional delays may occur.

​
Testing Endpoints

Before going live, you can validate your integration by testing endpoints in the dashboard:

  1. Navigate to the Testing tab in your webhook console.

  2. Select an event type to test.

  3. Send an example payload to your endpoint.

  4. Watch the delivery attempt in real-time, inspect the full message details, and view logs.

This immediate feedback loop helps you catch configuration issues early, ensuring that your endpoint can properly handle events before moving into production.

Webhooks 101Event Catalog