standard-webhooks
The Standard Webhooks specification
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/standard-webhooks/standard-webhooks with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/standard-webhooks/standard-webhooks'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/standard-webhooks--standard-webhooks)HTML
<a href="/listings/standard-webhooks--standard-webhooks"><img src="/api/listings/standard-webhooks--standard-webhooks/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 162 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <h1>
- <a style="text-decoration: none" href="https://www.standardwebhooks.com">
- <img width="360" src="./assets/brand.svg" />
- </a>
- </h1>
- Open source tools and guidelines for sending webhooks easily, securely, and reliably
- [](https://www.npmjs.com/package/standardwebhooks)
- [](https://pypi.org/project/standardwebhooks/)
- ## Introduction
- Webhooks are becoming increasingly popular and are used by many of the world's top companies for sending events to users of their APIs. However, the ecosystem is fragmented, with each webhook provider using different implementations and varying quality. Even high quality implementations vary, making them inherently incompatible. This fragmentation is a pain for the providers and consumers, stifling innovation.
- For consumers, this means handling webhooks differently for every provider, relearning how to verify webhooks, and encountering gotchas with bespoke implementations. For providers, this means reinventing the wheel, redesigning for issues that have already been solved (security, forward compatibility, etc.).
- We propose a simple solution: standardize webhooks across the industry. This design document outlines our proposal, a set of strict webhook guidelines based on the existing industry best practices. We call it "Standard Webhooks".
- We believe "Standard Webhooks" can do for webhooks what JWT did for API authentication. Adopting a common protocol that is consistent and supported by different implementations will solve the above issues, and will enable new tools and innovations in webhook ecosystem.
- To achieve this, we have created an open source and community-driven set of tools and guidelines for sending webhooks.
- ## What are Webhooks?
- Webhooks are a common name for HTTP callbacks, and are a way for services to notify each other of events. Webhooks are part of a service's API, though you can think of them as a sort of a "reverse API". When a client wants to make a request to a service they make an API call, and when the service wants to notify the client of an event the service triggers a webhook ("a user has paid", "task has finished", etc.).
- Webhooks are server-to-server, in the sense that both the customer and the service in the above description, should be operating HTTP servers, one to receive the API calls and one to receive the webhooks. It's important to note that while webhooks usually co-exist with a traditional API, this is not a requirement, and some services send webhooks without offering a traditional API.
- ## Read the specification
- The latest draft specification can be found at [spec/standard-webhooks.md](./spec/standard-webhooks.md) which tracks the latest commit to the main branch in this repository.
- The human-readable markdown file is the source of truth for the specification.
- ## Reference implementations
- There are reference implementations for the signature verification theme for a variety of languages, including:
- - [Python](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/python) - `standardwebhooks` on PyPi.
- - [JavaScript/TypeScript](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/javascript) - `standardwebhooks` on NPM.
- - [Java/Kotlin](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/java) - `com.standardwebhooks:standardwebhooks` on Maven Central.
- - [Rust](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/rust) - `standardwebhooks` on crates.io.
- - [Go](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/go) - `github.com/standard-webhooks/standard-webhooks/libraries/go` as a Go module.
- - [Ruby](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/ruby) - `standardwebhooks` on RubyGems.
- - [PHP](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/php)
- - [C#](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/csharp) - `StandardWebhooks.StandardWebhooks` on nuget.
- - [Elixir](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/elixir)
- ## Using the libraries
- All of the reference implementations share the same API (adapted to each language's conventions). The examples below use JavaScript; see each library's README for its exact usage.
- ### Symmetric signatures
- Both sides share the same `whsec_` secret.
- ```javascript
- import { Webhook } from "standardwebhooks";
- const wh = new Webhook("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw");
- // Producer: sign
- const signature = wh.sign(msgId, timestamp, payload);
- // Consumer: verify (the payload must be the raw request body, exactly as received)
- const event = wh.verify(payload, headers);
- ```
- ### Asymmetric signatures
- The producer signs with a private key, and gives consumers the public key and the ID of their endpoint. A single key pair can be used for all endpoints.
- Producer, signing using an HSM or a KMS (recommended):
- ```javascript
- import { WebhookAsymmetric } from "standardwebhooks";
- const hash = WebhookAsymmetric.signedContentHash(endpointId, msgId, timestamp, payload);
- const signature = WebhookAsymmetric.formatSignature(await hsm.sign(hash)); // Your HSM's ed25519 sign call
- // The whpk_ public key to give to consumers, from the raw key or the DER (SubjectPublicKeyInfo) your HSM returns
- const publicKey = WebhookAsymmetric.formatPublicKey(await hsm.getPublicKey());
- ```
- Producer, signing using a private key you hold yourself:
- ```javascript
- import { WebhookAsymmetricSigner } from "standardwebhooks";
- const signer = new WebhookAsymmetricSigner("whsk_...");
- const signature = signer.sign(endpointId, msgId, timestamp, payload);
- const publicKey = signer.publicKey(); // The whpk_ public key to give to consumers
- ```
- Consumer, verifying using the producer's public key(s) and the endpoint ID it gave you:
- ```javascript
- import { WebhookAsymmetric } from "standardwebhooks";
- const wh = new WebhookAsymmetric("ep_...", ["whpk_..."]);
- const event = wh.verify(payload, headers);
- ```
- Keys are rotated by the producer: consumers just add the new public key to the list (newest first).
- ## Community implementations
- - [C# (.NET)](https://github.com/codefactors/StandardWebhooks)
- - [Haskell](https://github.com/MercuryTechnologies/signet)
- - [Java](https://github.com/Cosium/standard-webhooks-consumer)
- - [Swift](https://github.com/m1guelpf/swift-standard-webhooks)
- ## Tools
- - [receiving-webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/skills/receiving-webhooks/): an [AI skill](https://www.skills.sh/docs) that teaches agents to verify webhooks the right way.
- ## Technical steering committee
- The Standard Webhooks initiative, the specification, and development of tooling is driven by the community and guided by the technical steering committee.
- Members (in alphabetical order):
- * [Brian Cooksey](https://github.com/bcooksey) ([Zapier](https://zapier.com/))
- * [Ivan Gracia](https://github.com/igracia) ([Twilio](https://twilio.com/))
- * [Jorge Vivas](https://github.com/jorgelob) ([Lob](https://lob.com))
- * [Matthew McClure](https://github.com/mmcc) ([Mux](https://mux.com))
- * [Nijiko Yonskai](https://github.com/nijikokun) ([ngrok](https://ngrok.com))
- * [Stojan Dimitrovski](https://github.com/hf) ([Supabase](https://supabase.com))
- * [Tom Hacohen](https://github.com/tasn/) ([Svix](https://www.svix.com))
- * [Vincent Le Goff](https://github.com/zekth) ([Kong](https://konghq.com))
- ## Compatible implementations
- Standard Webhooks has been adopted by a variety of companies including: OpenAI, Anthropic, Google Gemini, Kong, Svix, Supabase, Vanta, Drata, Etsy, PagerDuty, Twilio, TaskRabbit and many others.
- ## Example ecosystem benefits of Standard Webhooks
- We believe "Standard Webhooks" can do to webhooks what JWT did to API authentication. Having a common protocol that is consistent will enable a variety of implementations to interoperate, reducing the development burden on webhook consumers and enabling new uses. Some of these benefits include:
- - API Gateway signature verification: signature verification is a common challenge for webhook consumers. Standard Webhooks makes it possible for verification to be implemented directly in the API gateway, easily solving verification for consumers.
- - Having a set of libraries for signing and verification make webhook verification easier for scenarios where API gateways can't be used.
- - Workflow automation tools (such as Zapier, Make, Workato, and tray.io) can implement the signature verification themselves to ensure a secure integration and save the need for integration builders to reinvent the wheel every time.
- - Standard Webhooks will enable building tools to automatically generate SDK for webhook consumers that in addition to verifying the signature can also validate the schemas (using JSON Schema, OpenAPI or AsyncAPI definitions).
- - Many more...
- ## Related efforts
- There are a few complementary or partially overlapping efforts to standardize asynchronous event communication. This specification is compatible with the rest of them, and can either reuse existing efforts or benefit further from collaboration with them. The most notable of such efforts are:
- ### Active Projects
- - [OpenAPI](https://www.openapis.org/)
- - [AsyncAPI](https://www.asyncapi.com/)
- - [CloudEvents](https://cloudevents.io/)
- - [IETF HTTP Message Signatures](https://httpwg.org/http-extensions/draft-ietf-httpbis-message-signatures.html)
- ### In-active Projects
- - [RestHooks](https://github.com/zapier/resthooks)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.