Webhooks

Syncing team & user data with your backend

Webhooks are a powerful way to keep your backend in sync with Stack. They allow you to receive real-time updates when events occur in your Stack project, such as when a user or team is created, updated, or deleted.

For more information and a list of all webhooks, please refer to the webhook API reference.

Setting up webhooks

In the Stack dashboard, you can create a webhook endpoint in the “Webhooks” section. After creating this endpoint with your server URL, you will start receiving POST requests with a JSON payload at that endpoint. The event payload will look something like this:

1{
2  "type": "team.created",
3  "data": {
4    "id": "2209422a-eef7-4668-967d-be79409972c5",
5    "display_name": "My Team",
6    ...
7  }
8}

Testing webhooks locally

You can use services like Svix Playground or Webhook.site to test the receiving of webhooks or relay them to your local development environment.

Verifying webhooks

To ensure the webhook is coming from Stack (and not from a malicious actor) and is not prone to replay attacks, you should verify the request.

Stack signs the webhook payload with a secret key that you can find in the endpoint details on the dashboard. You can verify the signature using the Svix client library. Check out the Svix documentation for instructions on how to verify the signature in JavaScript, Python, Ruby, and other languages. Here is an quick example in JavaScript:

1import { Webhook } from "svix";
2
3const secret = "<from the dashboard>";
4const headers = {
5  "svix-id": "<from the webhook request headers>",
6  "svix-timestamp": "<from the webhook request headers>",
7  "svix-signature": "<from the webhook request headers>",
8};
9const payload = "<the webhook request body>";
10
11const wh = new Webhook(secret);
12// Throws on error, returns the verified content on success
13const payload = wh.verify(payload, headers);

If you do not want to install the Svix client library or are using a language that is not supported, you can verify the signature manually.

Event types

Please refer to the webhook endpoint API reference for more details on the available event types and their payload structures.

Examples

Some members of the community have shared their webhook implementations. For example, here is an example by Clark Gredoña that validates the Webhook schema and update a database user.