Webhooks

Introduction

Webhooks are how services notify each other of events.

At their core they are just a POST request to a pre-determined endpoint. The endpoint can be whatever you want, and you can just add them from the UI. You normally use one endpoint per service, and that endpoint listens to all of the event types.

For example, if you receive webhooks from Acme Inc., you can structure your URL like: https://www.example.com/acme/webhooks/.

The way to indicate that a webhook has been processed is by returning a 2xx (status code 200-299) response to the webhook message within a reasonable time-frame (15s).

It's also important to disable CSRF protection for this endpoint if the framework you use enables them by default.

Another important aspect of handling webhooks is to verify the signature and timestamp when processing them.

You can learn more about it in the signature verification section.

Adding an endpoint

In order to start listening to messages, you will need to configure your endpoints.

You can do this by navigating to the CarbonAPI admin portal, selecting a project, and reviewing the Webhooks section that opens at the bottom of the page. Adding an endpoint is as simple as providing a URL that you control and selecting the event types that you want to listen to.

If you don't specify any event types, by default, your endpoint will receive all events, regardless of type.

This can be helpful for getting started and for testing, but we recommend changing this to a subset later on to avoid receiving extraneous messages.

If your endpoint isn't quite ready to start receiving events, you can press the "with Svix Play" button to have a unique URL generated for you.

You'll be able to view and inspect webhooks sent to your Svix Play URL, making it effortless to get started.

Webhook contents

For batch endpoints, the webhook response will contain a pointer to the batch, rather than the actual contents, to reduce the amount of sensitive data passed around:

{
  "batchId": "abc123",
  "organisationId": "def456",
  "projectId": "abc789",
  "timestamp": "2025-09-10T18:10:39.092Z",
  "type": "transaction.batch.completed"
}

Key output parameters

batchId - this is the name of your batch, you'll then make a call to retrieve the batch, which contains the information you need.
type - the webhook type, use this to decide how to process the response

Testing Endpoints

Once you've added an endpoint, you'll want to make sure its working.

The "Testing" tab in the Webhook page lets you send test events to your endpoint.

After sending an example event, you can click into the message to view the message payload, all of the message attempts, and whether it succeeded or failed.

Verifying Signatures

Our SDKs handle signature verification for you. See TypeScript SDK for more information.,