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.
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.,