Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/standard-webhooks--standard-webhooks/badge.svg)](/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

i

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.

  1. <h1>
  2. <a style="text-decoration: none" href="https://www.standardwebhooks.com">
  3. <img width="360" src="./assets/brand.svg" />
  4. </a>
  5. </h1>
  6. Open source tools and guidelines for sending webhooks easily, securely, and reliably
  7. [![NPM Downloads](https://img.shields.io/npm/dm/standardwebhooks?logo=npm)](https://www.npmjs.com/package/standardwebhooks)
  8. [![Pypi Downloads](https://img.shields.io/pypi/dm/standardwebhooks?logo=pypi)](https://pypi.org/project/standardwebhooks/)
  9. ## Introduction
  10. 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.
  11. 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.).
  12. 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".
  13. 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.
  14. To achieve this, we have created an open source and community-driven set of tools and guidelines for sending webhooks.
  15. ## What are Webhooks?
  16. 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.).
  17. 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.
  18. ## Read the specification
  19. 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.
  20. The human-readable markdown file is the source of truth for the specification.
  21. ## Reference implementations
  22. There are reference implementations for the signature verification theme for a variety of languages, including:
  23. - [Python](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/python) - `standardwebhooks` on PyPi.
  24. - [JavaScript/TypeScript](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/javascript) - `standardwebhooks` on NPM.
  25. - [Java/Kotlin](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/java) - `com.standardwebhooks:standardwebhooks` on Maven Central.
  26. - [Rust](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/rust) - `standardwebhooks` on crates.io.
  27. - [Go](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/go) - `github.com/standard-webhooks/standard-webhooks/libraries/go` as a Go module.
  28. - [Ruby](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/ruby) - `standardwebhooks` on RubyGems.
  29. - [PHP](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/php)
  30. - [C#](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/csharp) - `StandardWebhooks.StandardWebhooks` on nuget.
  31. - [Elixir](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/elixir)
  32. ## Using the libraries
  33. 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.
  34. ### Symmetric signatures
  35. Both sides share the same `whsec_` secret.
  36. ```javascript
  37. import { Webhook } from "standardwebhooks";
  38. const wh = new Webhook("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw");
  39. // Producer: sign
  40. const signature = wh.sign(msgId, timestamp, payload);
  41. // Consumer: verify (the payload must be the raw request body, exactly as received)
  42. const event = wh.verify(payload, headers);
  43. ```
  44. ### Asymmetric signatures
  45. 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.
  46. Producer, signing using an HSM or a KMS (recommended):
  47. ```javascript
  48. import { WebhookAsymmetric } from "standardwebhooks";
  49. const hash = WebhookAsymmetric.signedContentHash(endpointId, msgId, timestamp, payload);
  50. const signature = WebhookAsymmetric.formatSignature(await hsm.sign(hash)); // Your HSM's ed25519 sign call
  51. // The whpk_ public key to give to consumers, from the raw key or the DER (SubjectPublicKeyInfo) your HSM returns
  52. const publicKey = WebhookAsymmetric.formatPublicKey(await hsm.getPublicKey());
  53. ```
  54. Producer, signing using a private key you hold yourself:
  55. ```javascript
  56. import { WebhookAsymmetricSigner } from "standardwebhooks";
  57. const signer = new WebhookAsymmetricSigner("whsk_...");
  58. const signature = signer.sign(endpointId, msgId, timestamp, payload);
  59. const publicKey = signer.publicKey(); // The whpk_ public key to give to consumers
  60. ```
  61. Consumer, verifying using the producer's public key(s) and the endpoint ID it gave you:
  62. ```javascript
  63. import { WebhookAsymmetric } from "standardwebhooks";
  64. const wh = new WebhookAsymmetric("ep_...", ["whpk_..."]);
  65. const event = wh.verify(payload, headers);
  66. ```
  67. Keys are rotated by the producer: consumers just add the new public key to the list (newest first).
  68. ## Community implementations
  69. - [C# (.NET)](https://github.com/codefactors/StandardWebhooks)
  70. - [Haskell](https://github.com/MercuryTechnologies/signet)
  71. - [Java](https://github.com/Cosium/standard-webhooks-consumer)
  72. - [Swift](https://github.com/m1guelpf/swift-standard-webhooks)
  73. ## Tools
  74. - [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.
  75. ## Technical steering committee
  76. The Standard Webhooks initiative, the specification, and development of tooling is driven by the community and guided by the technical steering committee.
  77. Members (in alphabetical order):
  78. * [Brian Cooksey](https://github.com/bcooksey) ([Zapier](https://zapier.com/))
  79. * [Ivan Gracia](https://github.com/igracia) ([Twilio](https://twilio.com/))
  80. * [Jorge Vivas](https://github.com/jorgelob) ([Lob](https://lob.com))
  81. * [Matthew McClure](https://github.com/mmcc) ([Mux](https://mux.com))
  82. * [Nijiko Yonskai](https://github.com/nijikokun) ([ngrok](https://ngrok.com))
  83. * [Stojan Dimitrovski](https://github.com/hf) ([Supabase](https://supabase.com))
  84. * [Tom Hacohen](https://github.com/tasn/) ([Svix](https://www.svix.com))
  85. * [Vincent Le Goff](https://github.com/zekth) ([Kong](https://konghq.com))
  86. ## Compatible implementations
  87. 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.
  88. ## Example ecosystem benefits of Standard Webhooks
  89. 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:
  90. - 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.
  91. - Having a set of libraries for signing and verification make webhook verification easier for scenarios where API gateways can't be used.
  92. - 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.
  93. - 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).
  94. - Many more...
  95. ## Related efforts
  96. 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:
  97. ### Active Projects
  98. - [OpenAPI](https://www.openapis.org/)
  99. - [AsyncAPI](https://www.asyncapi.com/)
  100. - [CloudEvents](https://cloudevents.io/)
  101. - [IETF HTTP Message Signatures](https://httpwg.org/http-extensions/draft-ietf-httpbis-message-signatures.html)
  102. ### In-active Projects
  103. - [RestHooks](https://github.com/zapier/resthooks)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.