This guide walks you through setting up webhooks for various integrations in your Agentic Team OS.

Webhooks are configured in the API Template.

​
Overview

Webhooks are essential for handling asynchronous events from:

  • Stripe (payments and subscriptions)
  • Clerk (user authentication)

The checkout webhook is implemented in the billing module of the control plane using the AMU Pattern.

This guide covers setting up the webhook not implementing the billing logic.

By default a completed checkout session will trigger an update to the customers API with a refill to their API key.

Only the checkout.session.completed event is supported.

You can implment a more custom billing model by modifying the billing module.

​
Configure Your Stripe Webhooks

  1. Configure Stripe Dashboard

    • Go to the Stripe Dashboard
    • Add a new webhook endpoint with your API URL: https://api.${DOMAIN_NAME}/checkout-webhook
    • Copy the webhook signing secret
    • Add it to your secrets as StripeSecretKey

  2. Configure your stripe product

    • Go to the Stripe Dashboard
    • Copy the price ID for your product
    • Add it to your secrets as StripePriceId

  3. Enable Events

    • Select the events you want to listen for
    • checkout.session.completed

  4. Testing Webhooks

    # Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Forward webhooks locally
stripe listen --forward-to localhost:3001/checkout-webhook

# Trigger test webhook
stripe trigger checkout.session.completed

    Deploy or start your API

    cd api 
npx sst dev --stage dev

Once you are satsified with the webhook deploy it to your production environment.

To learn more about Stripe webhooks click here

​
Clerk Webhooks

Clerk webhooks are also implemented in the control plane.

Preconfigured for you is a clerk webhook that will trigger when a user signs up.

This webhook will create a new user in the Database and create a new API key for them with Unkey.

Clerk webhooks are really extensible and go beyond just a trigger on signup.

​
Configure Your Clerk Webhooks

Set up webhook endpoint

  1. Go to the Webhooks page in Clerk Dashboard
  2. Select “Add Endpoint”
  3. Enter your endpoint URL https://${stage}-api.${DOMAIN_NAME}/signup-webhook
  4. Select the user.created event which triggers when a new user registers
  5. Create the endpoint

Add Signing Secret

  1. Copy the Signing Secret from your endpoint’s settings page
  2. Add it to your .env.{stage} file as ClerkWebhookSecret

Test the webhook by creating a new user in the Clerk Dashboard.

  1. Create a JWT template in the clerk dashboard
  2. Login with a test user
  3. Generate a JWT token using the template via the console
await window.Clerk.session.getToken({ template: '<YOUR TEMPLATE NAME>' })

This will return a JWT token that you can use to test the webhook that you can too env.test where needed.

There are other methods to generate a JWT token for testing, but this is the most straightforward.

Learn more about Clerk JWT tokens here

Learn more about Clerk Webhooks here

Was this page helpful?