Skip to main content

Documentation Index

Fetch the complete documentation index at: https://stackauth-e0affa27-apps-support.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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 payload schemas and each webhook event, see 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: 
{
  "type": "team.created",
  "data": {
    "id": "2209422a-eef7-4668-967d-be79409972c5",
    "display_name": "My Team",
    ...
  }
}

​
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 are example handlers across the supported frameworks:
Next.js
// app/api/webhooks/stack/route.ts
import { Webhook } from "svix";

export async function POST(request: Request) {
  const secret = process.env.STACK_WEBHOOK_SECRET!;
  const payload = await request.text();
  const headers = {
    "svix-id": request.headers.get("svix-id") ?? "",
    "svix-timestamp": request.headers.get("svix-timestamp") ?? "",
    "svix-signature": request.headers.get("svix-signature") ?? "",
  };

  const wh = new Webhook(secret);
  // Throws on error, returns the verified content on success.
  const verifiedPayload = wh.verify(payload, headers);

  return Response.json({ ok: true, type: verifiedPayload.type });
}
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

These are the type values you may receive. Each links to its API reference page.

​
Examples

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