Introducing Webhook Skills for Agents

A good chunk of the webhook code being written today isn't typed by a human but by a coding agent, and the human reads it, nods, and merges it.

That's mostly great. Webhooks are a well understood problem, and the code is repetitive enough that an agent should be able to write it. The trouble is that webhook code has a nasty property: the wrong version looks almost like the right version. It compiles, it passes review, and then something fails in production for reasons nobody can reproduce locally.

So today we are releasing Webhooks Agent Skills, a set of webhook skills that cover the two sides of that problem. Some of them teach an agent how to integrate Svix, so the code it writes against our API looks like the code we would have written. One of them teaches an agent how to build a webhook receiver, for any sender, whether or not Svix is anywhere in the picture.

What is an Agent Skill?

An Agent Skill is a folder with a Markdown file in it. The Markdown file has a name, a description of when it applies, and then a body of instructions. Your agent reads the descriptions, decides which skill is relevant to what you asked, and loads the body into its context.

That's really the whole idea. What makes it interesting is the loading part. The instructions aren't sitting in your context window all the time, competing with your actual code for attention. They show up when you touch a webhook handler and stay out of the way when you don't.

Skills are supported by Claude Code, Cursor, and a growing list of other agents. Ours live in the svix/ai repo, which is the canonical source.

Why your agent needs them

Agents aren't careless about webhooks. They're working from bad assumptions, and there are a few reasons why:

• The training data is mostly wrong. Public webhook code skews toward blog snippets and tutorials that skip security best practices and lean on outdated APIs, sometimes producing code that doesn't even run.
• Nothing pushes back. Wrong webhook code compiles, passes review, and only fails on a live delivery against a real signature. An agent that can run your tests still has no way to learn it got this wrong.
• Every provider is a little different. Header names, secret formats, and replay windows vary, so an agent averages across all of them and lands on something that matches none of them.

None of these are exotic mistakes. They're the ones somebody who has done this once already would never make again. That's exactly the knowledge a skill can carry.

What's in the box

There are two webhook skills.

Integrating Svix

svix-receiving-webhooks is everything an agent needs to work with Svix. You can get through a quickstart that will help you make a project sending its first webhook: Grab an API key, install the SDK for whatever language the repo is written in, create an Application per customer, send a message, subscribe an endpoint. It's for the case where you don't want an architecture conversation but just want a webhook to arrive.

But if you need help preparing a large migration to Svix, the integration-plan comes to help: It will deeply scan your codebase to understand its current architecture and write a design doc with real decisions: Multi-tenant routing, an event catalog, embedding the App Portal, or migrating off a webhook system you already run.

Or, if you're maintaining an existing svix integration you'll trigger the best-practices, which will keep the code looking like it was written by one of the Svix engineers: It'll help you model your costumers the right way, the choices that are painful to reverse later, the features people don't know to reach for. It also teaches the agent to use the Svix CLI, which is worth having around for the things an SDK is a clumsy fit for, like relaying live webhooks to your laptop or provisioning a hundred applications from a shell script.

Consuming webhooks from anyone

receiving-webhooks Is a general skill for writing a webhook receiver, whoever the sender is: Stripe, GitHub, an internal service, us. It's the accumulated set of rules we'd give anyone writing a handler, covering signature verification, how and when to respond, idempotency, and the traps that make a handler fail in ways that are miserable to debug. It leans on Standard Webhooks where a provider supports it.

How to use it

One command, from the repo you're working in:

npx skills add svix/ai

That's it. Your agent will pick the right webhook skill based on what you ask it next. Say "add Svix to this project" and you get the quickstart. Say "I need to figure out how to wire Svix into our multi-tenant setup" and you get the planner. Say "write me an endpoint that handles Stripe events" and you get the receiver skill, which never mentions us at all.

Wrapping up

Coding agents are going to write your webhook code whether or not we help them, on both ends of the pipe. We'd rather they wrote good code on both.

The webhook skills are MIT licensed and live in our AI Repo. If your agent does something a skill should have prevented, that's a bug, so please open an issue. Pull requests are very welcome too, especially from people who've hit a footgun we haven't documented yet.

For more content like this, make sure to follow us on Twitter, Github, or RSS for the latest updates for the Svix webhook service, or join the discussion on our community Slack.