Skip to content

Webhook Producer Standards #105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

Webhook Producer Standards #105

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2ee79f4
First draft
travisgosselin Jun 16, 2025
41c40d6
next draft
travisgosselin Jun 16, 2025
847efff
A few copilot updates.
travisgosselin Jun 16, 2025
0cb4cf0
Back to original webhook consumer guidelines for now.
travisgosselin Jun 16, 2025
b9f3031
Merge branch 'main' into feature/webhook-producer
travisgosselin Jun 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions standards/request-response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -593,6 +593,44 @@ Sps-Idempotency-Key: a // not enough entropy, and below
Sps-Idempotency-Key: KG5Lxw!@#$&*()FBepaKHyUD // non-url-safe special characters can be limiting for usage or later reference
```

<hr />

#### Sps-Signature
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • I know the formula is given below, but I think either a separate page or a linkable header specifically addressing the Sps-Signature might be a good idea. Call out the formula specifically, leave a place for any implementation notes for creating and verifying the signature (i.e. language-specific event), etc.
  • In a separate section, it might be good to include an example... or a couple examples that could be used by someone to verify their implementation (i.e. test vectors).
  • One thing I think is important to make sure to call out is inclusion of the timestamp. We talking about preventing reuse of the signature, but that could be made more clear by indicating the timestamp is included within the signature.
  • Is just the timestamp header enough? Or the whole request sans the Signature header?
  • Should we have a Salt? To add additional entropy and even stronger prevention of reuse? It could be handled by adding a header and including all headers in the hmac.
  • Any comments on the payload? Like, use the payload as is?
  • Any concerns about how long the payload gets and computing the hmac?


**Type**: Request

**Support**: OPTIONAL

**Description**: Contains a cryptographic signature of the request payload. This signature is used to verify the authenticity and integrity of a request. The signature is typically computed using a shared secret established between the producer and consumer, typically using HMAC with SHA-256. The hash function should be specified in the header value: `SPS-Signature: sha256=<HMAC hex digest>`. The primary usage of this header is for [webhook security](webhooks.md#webhook-requests).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would we ever need to rotate keys? If so, how would this scheme work without something like a key id?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another option would be to have multiple signatures included in the "Sps-Signature" header and validate that any of them match (e.g., Sps-Signature: SHA256-0123456789; SHA256-0987654321).

During rotation, you would add a new shared key to the registration and there would be two active, producer creates signatures for both the keys and consumer validates that any of the included signatures matches (the old one will), the consumer updates their shared key and begins to validate the new signature, old shared key is removed and producer only creates a single signature.

That might also be useful to provide a pathway to implement a new version of the signature algorithm in the same way and give consumers a chance to upgrade before removing the old signature (e.g., "Sps-Signature: V1-SHA256-0123456789; V2-SHA256-0987654321").


- The header value **MUST** be a valid HMAC digest of the request payload.
- The header value **SHOULD** be accompanied by a timestamp to prevent replay attacks. The timestamp can be included in the `Sps-Signature-Timestamp` header.

```
// CORRECT
Sps-Signature: sha256=4d3f8b2c1e5f6a7b8c9d0e1f2a3b4c5d6e7f8g9h0i1j2k3l4m5n6o7p8q9r0s1t2u3v4w5x6y7z8a9b0c1d2e3f4g5h6i7j8k9l0m
Sps-Signature: sha512=4d3f8b2c1e5f6a7b8c9d0e1f2a3b4c5d6e7f8g9h0i1j2k3l4m5n6o7p8q9r0s1t2u3v4w5x6y7z8a9b0c1d2e3f4g5h6i7j8k9l0m
```

<hr />

#### Sps-Signature-Timestamp

**Type**: Request

**Support**: OPTIONAL

**Description**: Used to indicate the timestamp of when the request was signed. This is used to prevent replay attacks by ensuring that the signature is only valid for a specific time window. The timestamp should be in ISO 8601 format (e.g., `2023-10-01T12:00:00Z`).

- The header value **MUST** be in ISO 8601 format.
- The header value **MUST** be included only if the `Sps-Signature` header is present.
- The header value **MUST** be a valid UTC timestamp.

```
// CORRECT
Sps-Signature-Timestamp: 2023-10-01T12:00:00Z
```

## MIME Types

### Standard MIME Types
Expand Down
Loading
Loading