golang has a great feature which is part of the toolchain to create examples: https://go.dev/blog/examples

The go library should implement it

I've been working on adding Standard Webhooks support for webhoox (tests here).

I'd be glad to bring the relevant parts over into this repo.

On https://www.standardwebhooks.com/#committee

Should be Supabase, not Supbase.

It's not super clear whether the headers of the HTTP message are also signed under webhook-signature. This should generally be the case so that they too are authenticated. This probably requires adding a section about canonicalizing the headers and including them in the signature computation.

This is a question I have always asked myself regarding webhooks.

Why not let the sender pass a token (originally crafted by the receiver) via the Authorization header?

Hey!

Thanks for building a tool to simulate requests in a manner compliant with Spec. It has been quite useful so far. I recently played with the tool on Google Chrome v123.0, MacOS and realized that the cURL request might be obscured if the payload is too long (see screenshot below for example). Was hoping to fix the site but wasn't too sure where to find the source. Would anyone be able to point me in the right direction?

If it's private that's fine too - would be keen to help move this along eitherways.

Let me know

Some ideas that came up:

1. Exposing the expected header names as constants, such as in #20
2. Having tests in all the libs that read from the same source for test data.
3. Implement "verify ignoring timestamp" like the go lib.

I'm sure there are many others. Just to make sure that the libs are all consistent and up to the same standard.

Hi,

I'm hoping to use Standard Webhooks for an internal project at Supabase. I was glancing through the repository after reading the specification and noticed that the JavaScript and Go libraries currently use symmetric verification and signing and that there doesn't seem to be an implementation for asymmetric verification and signing via ed25519 as per spec.

Can I check if this is something that's on the roadmap within the next three weeks and/or something that the committee would be open to accepting contributions on?

Let me know

Before starting to release the libraries we need to address some areas and workflows.

Content

Author

Currently some packages have author field set as Svix; i assume that was ported from the initial project created by Svix but i'd say we should change this to standard-webhooks. wdyt?
ref:

Urls

Lot of libs target strandard-webhooks/libraries.git which is now invalid. ref:

Release flow

Currently the release flow is for v* tags (ref:

• golang uses git tags for versionining which for our case will need to be libraries/vX.Y.Z
• What happens if there's a security bump on one library and not on the others? Do we trigger a release for all revisions for a patch?

I'd propose a strategy that each library has an independent versioning regarding PATCH releases but MINOR and MAJOR should be released at the same time, meaning all libraries should offer the same API to be able to be released.

Any idea welcome

Hi folks,

Apologies if this isn't the correct place, but I'm wondering if/why you haven't submitted this to a standards body. Seems like a great thing to go through the w3c or IETF process to become a full blown standard, rather than a vendor consortium document. I saw this which discussed related efforts.

Here's a list of the IETF working groups. I'm not familiar with all of them, but there may be a fit.

Is this something for the future, or an action you've considered and then discarded? If the latter, I'd love to know why. If the former, I know a few folks who work on standards who would good to chat with to discuss appropriate steps.

In the go example there is a very high probability that it will fail validation. In the following line the signature is created using time.Now(). However, the header is set in line 42 using ts.Unix() and ts was created at the top of the function (also using time.Now()). The difference may be in the milliseconds range, but it could be enough to cause a validation failure. The correct way to do it would be to use the ts value when creating the signature.

Hi 👋

Similarly to #126, we'd be interested in a NuGet package that we can install to implement webhook signature verification.

We could add this repository to the documentation, but copying the implementation across different projects seems inefficient.

I'd be happy to help if there are gaps in the implementation or the toolchain that we'd like addressed before publishing.

Thanks!

I couldn't find any previous discussion about this in the existing issues, so I'll ask here. What was the thought process behind publishing all the libraries in this one GitHub repository versus having a repository per library?

Some of the drawbacks I see to publishing it all in one repository (as is done now):

• You have to do extra work (in the form of a GitHub Action) to publish the releases to the required package repositories (e.g. publishing the PHP library to Packagist).
• Versioning is tied to the GitHub repository. If the Java lib has a bug that is fixed with an immediate bugfix, all other libraries also get a version bump.

Could you shed some light on the initial decision to put all the libraries in this one repository? Thanks in advance!

HTTP/2 only compresses the headers, so delivering webhooks with large payloads consumes a lot of bandwidth. It would be nice if a future version of the spec automatically compressed payloads above a certain threshold and required that recipients support the resulting content-encoding.

The spec currently misses a Definitions section where we would define terms of the spec used like producer, consumer and other terms that would come up in the spec.

I think it would be a good idea to include the webhook-id in the webhook payload as a required field. Consumers have an additional confirmation then that the webhook-id matches the id found in the webhook payload

For example based on the spec:

Headers:
webhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W\

Request Body:

{
  "id": "msg_2KWPBgLlAfxdpx2AI54pPJ85f4W\",
  "type": "contact.created",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "data": {
    "id": "1f81eb52-5198-4599-803e-771906343485"
  }
}

Edit: rather than say required field I should of said recommended field as the payload section is only a suggestion

I am wondering: Are the webhook- HTTP header fields defined somewhere? If so it would be great to reference that definition. If not it might make sense to consider defining these and then adding them to the IANA registry of HTTP header fields.

Few comments regarding the payload spec.

timestamp
Currently the spec states the timestamp of when the event occurred. This also should mention the format; i'd vote for RFC 3339 format: https://datatracker.ietf.org/doc/html/rfc3339

data
spec states: It can either be passed as part of the data property, or squashed as part of the top-level object.
The drawback of having it squashed at the top level is that it could create collision. Let's say i have user.created event and my payload is a full and we also return the type of user type: foo; we have a collision. We should enforce the producer/consumer data in the data property. Added to this that would make us able to provide a JSON Schema for the standard-webhooks spec.

full payload
I think we also should mention we might want to prefer using thin payloads because it reduces the potential of leeking PIIs over the channels.

The usage of python setup.py (as a command line tool) is deprecated according to this document.

It would be better to use build instead. build is a simple python packaging build frontend.

• pip install build~=1.0.3
• pyproject-build . --sdist (not generating .whl file)

When I tested in a local environment, I confirmed that it worked without any code change. (but specifying build-system in pyproject.toml is recommended) After build is used, the python library can define package specifications declaratively in pyproject.toml according to PEP 517, and PEP 518.

How do you think? Before the contribution, I'd like to ask maintainers for the opinions.

I'd like to suggest a few improvements to the asymmetric signature scheme born out of @hf's comments and the ensuing discussion at #25 (comment) as well as feedback from @awolk.

The problem

Symmetric signatures are fast and simple to implement (just a simple HMAC256 of the content), however they pose challenges when it comes to key distribution and keeping it a secret. With symmetric signatures everyone with the key can forge webhook messages, which includes the webhook consumers themselves or any verifier working on their behalf as well. This also means that there needs to be built-in support for secret rotation which is another operational hassle.

The solution to the above problem is utilizing asymmetric signatures. While they are much more resource intensive and implementations are less ubiquitous than their symmetric counterpart (HMAC256), key distribution becomes a non-issue, and it allows for additional benefits such as storing the signing key in an HSM for added security.

The spec already supports ed25519 based asymmetric signing, but the way it's currently done can be improved to further simplify the operational burden, security characteristics, and ease of use. The main limitation with the current recommendation is that it's unclear that for it to be secure it requires a different key per endpoint, even for the asymmetric case. This means that people can easily misuse the recommendations (and have security issues), and anyhow they can't have the benefits of having just one global key pair.

Why does the current implementation doesn't allow for one global key pair?

Because different customers of the same service will be able to trick the service into sending messages to another customer endpoint, and that customer endpoint will trust it because it's coming from the service.

Let's consider the following example: we have a service called ACME, an innocent customer called Alice, and an evil attacker called Eve. Alice uses ACME, with the endpoint url https://alice.com/webhooks/acme and verifies signatures using the ACME key pair. Eve, wanting to attack Alice, signs up to ACME and also creates an endpoint with the url https://alice.com/webhooks/acme. Messages sent from Eve's account will now be sent to Alice's endpoint, and since they are signed with the same key the signature will be valid. Now Eve is able to send messages to Alice's endpoint, and these message pass validation. All it has to do is be able to trick ACME to send messages that she controls which is a common feature in many implementations. Even if it wasn't a common feature, many implementations can be manipulated to send "close enough" information that can interfere with Alice's systems. Either way, this issue significantly increases the attack surface and opens implementations to vulnerabilities.

Suggested changes

Change to P-256

I'd like bring up potentially changing the recommendation to P-256 instead of ed25519. While ed25519 is considered better, P-256 is approved by FIPS-140 and ed25519 isn't which is a requirement for many implementations. We could potentially support both, but I think that's unnecessarily friction and fragmentation.

Additionally, if we are changing to P-256, we may need to consider encoding the signature and keys in DER format to make sure it's widely supported by implementations.

Support (and recommend) having one global asymmetric key pair

In order to support having on global asymmetric key pair, we need to add another (per endpoint) identifier when doing asymmetric signatures. This identifier does not need to be secret or random, it just needs to be unique per consumer (it can be reused across the endpoints of the same consumer if they have more than one). One great candidate for this identifier is using the internal database identifier for the consumer, or if that's sensitive use some derivation of it or just generate an ID for this purpose. It's just important that this identifier won't change during the lifecycle of the endpoint so that the signatures always verify.

The signature scheme we want to follow is the same as what's recommended in the current version of the spec with a few small modifications.

The content to be signed is still: {msg_id}.{timestamp}.{payload}. This in now HMAC256 with the consumer id (discussed above) instead of with the secret (done in the symmetric case), and then signed using the global asymmetric key pair.

So the code would look something like this (psuedo code):

to_sign = "{msg_id}.{timestamp}.{payload}"
hashed_msg = hmac256(key=consumer_id, msg=to_sign)
signature = p256_sign(global_keypair, hashed_msg)

The hashed_msg extra step makes sure that consumers verify this message was indeed intended for them as part of the signature verification process (no way to accidentally forget to verify the ID).

For this to work, the consumer ID needs to be known to the consumer ahead of time. We recommend just updating the public key (whpk_...) to have this consumer ID encoded in it so that it's very easy to use and consumers don't need to copy two identifiers.
The suggested idea is similar to how JWTs are structured: base64 the public key and the consumer id separately and then concatenate them by using a full stop (.) as the delimiter, i.e: whpk_{base64_of_key}.{base64_of_consumer_id}.

The structure of the signatures doesn't need to change, as it's just a normal signature.

Per the payload specification, the payload body type, structure, shape, and required keys are not prescribed, though there are recommendations.

It seems as though the webhook metadata headers aim to mitigate this by providing an event's unique id, which I have interpreted as the idempotent id of a particular instance of an event:

The unique identifier is a unique identifier associated with a specific event triggered, and it remains the same no matter how many times a webhook that has failed is retried. The ID is often used as an idempotency key, which lets a consumer ensure that they only process a specific event once, even if sent multiple times maliciously, in error, or due to networking issues.

The lack of appropriate metadata will require new endpoints, or provider-defined (implementation detail) metadata, which appears contrary to the proposed goal of this standard.

Consider

A sample ecommerce system that integrates with payment provider foo and payment provider bar. Providing a webhook for providers to indicate the success of a transaction would be desirable using a single endpoint that could determine the event source so that the event could be routed through the appropriate code paths.

Let us assume that provider foo transmits data via https using serialized JSON, and provider bar uses a proprietary encrypted binary payload.

There is no method, via the spec, to determine if an event is sent by provider foo, or sent by provider bar, leaving the only methods to differentiate:

1. Using a different endpoint for each provider
2. Attempting to determine the provider by deserializing the payload - this depends entirely upon implementation details.

This is a side effect of the nature of the internet - a provider need not send a request from a particular ip block or domain, and not all events are required to come from the same origin. In theory, an event may come from one domain/ip block, and a retry for the idempotent event id may originate from a different domain or ip block. Potential examples of this may be a provider making use of hybrid cloud, with producers spread across different cloud providers (such as aws and azure) - these event producers may not be assigned a public domain if the services are egress-only.

Proposal

Italics to be interpreted per RFC-2119

Include webhook-source headers that must be populated by a producer (the thing sending events to a webhook endpoint). At minimum, this value must be unique per provider (for example, two services that send webhook events by provider foo may use the same value, but there must not be any collision with the values used by any other provider. It is recommended that producers use a unique reverse DNS format as in the Java package naming standards.

A producer should also include a webhook-type header to allow proper routing of payload deserialization in the event that a single provider (webhook-source) produces different events that may contain disparate payload formats.

The two proposed headers are complementary, though they may alternatively be combined into a single header using a fully-qualified (read: namespaced) event type, allowing multiple producers to use the same event type without collisions.

The standard webhook specification must define the format of said header, which is beyond the scope of this rfc at its current stage.

Rationale/Benefits

Providing lightweight metadata that is prescribed by the standard webhook specification will open the door for unified webhook endpoints that can handle a single logical event from multiple providers. In theory, it could also be used to provide a single universal webhook endpoint - how this is implemented is entirely up to event consumers.

With the standardized metadata, a consumer can make decisions about how to handle an event with minimal (cognitive or technical) overhead, i.e. without attempting to deserialize the event payload.

Alternative

To mitigate the considered issue, the standard webhook specification could instead prescribe compatible payload formats (i.e. JSON, protobuf) and a minimum required set of top-level keys in the payload (such as: source, type, event-uid, and then a data key to store what would currently be the payload or request body).

This approach seems overly restrictive, and potentially less flexible.

Encoding Bytes

In the spec so far, under the signature schemes it says:

base64 encoded, prefixed with whsec_ for easy identification.

base64 encoded, prefixed with whsk_ for the secret key, and whpk_ for the public key for easy identification.

Why was this scheme chosen, and what do the wh*_ prefixes mean?

Allow me to suggest some changes to this.

The spec says "base64 encoded" but there's actually two competing Base64 encodings in use today: Base64 standard (with = padding and non-URL-safe characters) and Base64-URL (without padding and with URL-safe characters). In some environments, like NodeJS, you can decode from any Base64 variant, and in others (Go, C, Rust) you have to specify it exactly.

I would suggest a change to the spec to specifically state Base64 or Base64-URL unambiguously.

Encoding the Secret

Why was the wh*_ prefix chosen and what does it mean? I can't think of a mnemonic for it.

In general though, I would suggest avoiding the re-implementation and re-specification of cryptographic primitives. JWT (and the associated JOSE and other RFCs) went down this route and ended up reimplementing ASN.1 messages that encoded cryptographic information. Libraries are still struggling with implementing these well, so it's my opinion that this spec should intentionally avoid reinventing the wheel from the get-go on this.

I would suggest we choose one or more accepted standards for encoding cryptographic keys and use those.

Personally I'm in favor of JWKS as it has matured sufficiently as a standard and library coverage is wide enough. Being JSON, makes it very easy to read as a human (unlike DER / ASN.1).

The singular availability of Ed25519 as an asymmetric algorithm needlessly limits the choices of asymmetric algorithms that can be used. RSA is still pretty commonly used. Use of hardware devices may not support EdDSA algorithms at all, but may be required by parties implementing the spec.

In short, let's defer to already existing and well-supported standards on encoding cryptographic key material so that we don't end up reinventing the wheel.

Discovery

One thing that OIDC did well with its JWTs is to specify a discovery mechanism for public keys, which completely decoupled the need to share secrets and other cryptographic material between "publisher" and "verifier."

Allow me to suggest the same. Instead of imagining yet-another versioning scheme about signatures, how they're encoded, and what key is being used, we could define the following:

• webhook-jwks A header that is a HTTPS URL where the verifier can fetch all asymmetric signing keys for the signature. If missing the publisher and verifier should have agreed upon cryptographic material out-of-band.
• webhook-key-id A header containing the unique key identifier that produced webhook-signature, which should reside within webhook-jwks. Must be present if webhook-jwks is present, optional otherwise.

This would allow for:

• Simple use-cases where publisher and verifier agree on a pre-shared key (identified with webhook-key-id so that we don't re-imagine a new spec).
• More complex use cases where the burden of the verifier having obtained the proper and currently trusted public key material is shifted to the publisher by using a HTTPS endpoint to publish its key material.

This would make it very easy to build libraries and flows with minimal ceremonies about key maintenance and scheduling.

In the same vein, allow me to finally re-introduce the JWT aud claim as the webhook-audience header. When the publisher of the webhook is a larger service with many customers, relying just on public keys can become difficult. Verifiers shouldn't just rely on cryptographic signatures to figure out if a webhook is meant for them; they should also check webhook-audience and identify if the payload was meant for them. This effectively solves most SSRF cases as well, since the receiver should reject payloads that they're not listening (hence audience) for.

Questionable Cryptographic Recommendations

I saw these considerations and wanted to challenge them:

Additional considerations:

Signing keys should be unique per endpoint for symmetric signatures, and unique per endpoint (or potentially customer) for asymmetric signatures. Reusing keys across customers can lead to security issues!
It's almost always recommended to choose symmetric signatures when possible, as the performance implications of asymmetric signatures are quite severe.

Specifically:

Reusing keys across customers can lead to security issues!

This is true if there's no additional mechanism such as my proposal for webhook-audience above. Relying just on cryptography for identification is not a great idea; this is why websites today can use the same public key in their TLS cert, but advertise a different CN.

It often is much easier, security wise, to have one set of private keys residing in a hardware security module for the whole platform (that publishes webhooks) rather than maintain many signing keys per customer / endpoint. Hardware modules are not cheap (nor are services like AWS KMS), so it's cost-prohibitive to maintain one-per-customer of those. Some platforms may be required to use hardware modules (especially FIPS compliant ones) by compliance or law for any cryptography.

It's almost always recommended to choose symmetric signatures when possible, as the performance implications of asymmetric signatures are quite severe.

In fact, our recommendation should be the exact opposite. Asymmetric signatures are marginally slower (compute-wise) than symmetric signatures. Performance is a non-goal in this space, as having good security practices is more important than shaving sub-microsecond performance issues.

By all accounts, it's much worse if anyone -- even for experiments -- uses symmetric keys. Yes, they're useful in some cases, but our recommendation should always be for people to use asymmetric keys. It's much easier to rotate them when/if they leak (going back to my webhooks-jwks recommendation!), no secrets need to be shared, only public information (so only one system component needs to know the private key), etc.

In general I would strive to avoid any unfounded (who recommends and where?) or superfluous security recommendations in hopes of not leading library implementers and developers astray from the main security goals.

I have some thoughts around this that I'll find some time to write here. I just wanted to open this to have a place to collect feedback.

Observation

Looking at the implementation of the Python library, I see that only JSON encoding is supported -- and used to generate request signature.

Question

The project's aim is to standardise webhooks across many languages. My question is, are you planning to add support for other text-based encodings such XML, CSV, TSV, YAML, etc., for Python and other languages?

We need to make a release of the libraries

How about specifying the content-type of the webhook request in the spec?

I don't have a definite opinion on this, just a suggestion.

• content-type: application/json
  • It is the most common and standard value.
• content-type: application/vnd.standard-webhooks+json (such as application/vnd.go.cd.v1+json, application/vnd.github+json)
  • It follows vendor-specific MIME types.
  • Users can clearly understand that the webhook requests respect the standard-webhooks.
  • It is effective for gradually opt-in or switching from existing webhook consumer implementations. Through the content-type header, user can check whether it is a standard-webhook request and can perform additional authentication logic.
  • Some candidates:
    1. application/vnd.standard-webhooks+json
    2. application/vnd.standard-webhooks.v1+json
    3. application/vnd.standardwebhooks+json
    4. application/vnd.standardwebhooks.v1+json

There are at least two ways to go about it:

1. A normal ping that gets invoked every X minutes/hours and just verifies it still returns 2xx. If it does, keep it up, if it fails at least Y times, disable. This can also be used when first adding an endpoint to make sure it's configured correctly.
2. Expect the endpoint to pass a test to make sure that it has the key. This is potentially better for security, as we know the endpoint owns the key we expect it to have. The problem is that the secret is only available after the endpoint is created so this will fail in the beginning for sure. We could make it delayed, so that it only checks after a certain grace period, though is it useful enough to warrant the trouble?

Currently every library defines their own set of test data. eg:

• standard-webhooks/libraries/javascript/src/webhook.test.ts

  Lines 7 to 9 in ff0f07f

  	const defaultMsgID = "msg_p5jXN8AQM9LWM0D4loKWxJek";
  	const defaultPayload = `{"test": 2432232314}`;
  	const defaultSecret = "MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

• standard-webhooks/libraries/go/webhook_test.go

  Lines 13 to 15 in ff0f07f

  	var defaultMsgID = "msg_p5jXN8AQM9LWM0D4loKWxJek"
  	var defaultPayload = []byte(`{"test": 2432232314}`)
  	var defaultSecret = "MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

• etc.

We should at least consider a common set of data to be sure all implementations behave the same.

https://cloudevents.io/ is standard that is used by most cloudvendors for exchanging events between systems.

A webhook payload looks a lot like a cloudevent payload, or is there a significant difference?

Leaning on an already used standard like cloud-events for payloads might increase the adoption of this standard. This also focusses this standard on the consumer / producer interactions (like security, reliability).

Was trying to install standardwebhooks npm package but none is found :(

It would be awesome to have this setup in https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries/go.

For your reference https://go.dev/doc/tutorial/create-module, please advise if any help is needed.

PHP lib is currently not tested. We need to create a workflow for it.

It seems like these 2 pages works incorrectly for standard webhook type:

• https://www.standardwebhooks.com/simulate
• https://www.standardwebhooks.com/verify

I tried to verify my own created webhook and also simulated using this page but it is different from the description in specs + different from multiple online clients.

PS: I know that it appends v1 prefix but still it is different, see the pictures below. Shopify webhook type works correctly on the other hand (probably other types as well)

Simulated one

• https://www.standardwebhooks.com/simulate

Other clients

• https://www.devglan.com/online-tools/hmac-sha256-online

• https://www.javainuse.com/hmac

Currently we are maintaining a set of libraries which have dependencies.
Maintaining everything up to date and out of security vulnerability would be quite a mess to do it manually.

I suggest we use Renovate which supports all the language we support.

wdyt?