Secure Webhook Token (SWT)

Introduction The increasing use of webhooks requires a secure, standardized approach to authorizing webhook requests and verifying the sender's authenticity. The SWT specifies a JWT-based structure, which includes unique claims tailored for webhook events. This specification mandates that all tokens must be transmitted using HTTP POST requests (see ), with the token in the Authorization header and event data in the request body, ensuring secure transmission and optimal compatibility with typical HTTP implementations.

Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" . The interpretation should only be applied when the terms appear in all capital letters.

Secure Webhook Token (SWT) Overview This specification defines required claims within the JWT payload and prescribes the transport protocol as HTTP POST. The token is transmitted in the Authorization header while the webhook event data is sent in the request body. These constraints ensure interoperability across diverse systems and provide a consistent approach to webhook authorization.

Transport Requirements SWTs MUST be transmitted using HTTP POST requests only. The token MUST be included in the Authorization header using the Bearer scheme, while the webhook event data MUST be sent in the request body.

Token Size Limitation Recommended Maximum Token Size: While there is no strict maximum size for an SWT, the token SHOULD be kept concise, containing only essential claims to support efficient processing and minimize resource usage. The primary use case for SWTs is to securely authorize and trigger events rather than transmit extensive data. Header Size Considerations: Since the token is transmitted in the Authorization header, implementers should be aware of HTTP header size limits imposed by web servers and proxies. Most web servers have a default maximum HTTP header size of 8KB, though this can often be configured. To ensure broad compatibility, the JWT token itself SHOULD remain reasonably small (typically under 4KB).

JWT Structure An SWT comprises the following:

Header

alg: Specifies the signing algorithm , typically "HS256" (HMAC SHA-256).
typ: Specifies the token type, which MUST be "SWT". This distinguishes Secure Webhook Tokens from generic JWTs and enables recipients to recognize and process them according to this specification.

Example Header Structure

Payload The payload contains the following required claims, carefully chosen to meet security and identification needs:

webhook: Custom claim specific to this specification.
- event: Describes the webhook event type (e.g., "payment.received"). Values should be concise to meet the size limitations.
- hash (OPTIONAL): The cryptographic hash of the request body (see Request Body Integrity). This field MUST be present when the request body is non-empty and MUST be omitted when the request body is empty.
- retry_count (OPTIONAL): A non-negative integer indicating the delivery attempt number (0 = initial attempt, 1+ = retry). See JWT webhook claim for detailed specification.
iss (Issuer): Identifies the token issuer (e.g., a unique name or domain representing the entity). Short, meaningful identifiers are RECOMMENDED.
sub (Subject) (OPTIONAL): While traditionally used to identify the principal subject of a JWT, the sub claim is not required in SWT. The purpose and intent of the token are unambiguously defined by the webhook claim. However, implementers may include sub to identify the system, service, or entity responsible for issuing the token, if such context is useful.
exp (Expiration): Specifies the token's expiration time as a Unix timestamp. This prevents tokens from being valid indefinitely.
nbf (Not Before): Specifies the earliest time the token is considered valid, using a Unix timestamp.
iat (Issued At): The timestamp when the token was issued, aiding in token age validation.
jti (JWT ID): A unique identifier for each token to prevent replay attacks. A UUID or similarly unique identifier is RECOMMENDED.

Example Payload Structure

SWT payload with empty body (notification only):

SWT payload with body content:

SWT payload for retry attempt:

Request Body Integrity

Overview To ensure payload integrity when sending body content, webhook requests with non-empty request bodies MUST include a cryptographic hash of the request body. Instead of using separate fields for algorithm and value, a self-describing hash field is used: This format allows the server to interpret the algorithm dynamically and accept or reject hashes according to its policies.

Format hash = "<algorithm>:<hash_value>"

<algorithm>: The cryptographic hash algorithm, using standardized names such as sha-256, sha-512, sha3-256.
<hash_value>: The lowercase hexadecimal representation of the hash of the request body. Hexadecimal encoding is REQUIRED for interoperability.

Examples

Server-side Processing

Parse the hash string to separate algorithm and value.

Validate the algorithm against the server’s allowed list.
Compute the hash of the received payload using algo.
Compare computed hash with value.
- If they match → payload integrity verified.
- If they do not match → reject the webhook request.

Recommendations

Algorithm Registry: Use standardized algorithm names aligned with the IANA Named Information Hash Algorithm Registry to avoid ambiguities.
Extensibility: New hash algorithms may be introduced without changing the JSON schema.
Security Note: Do not accept weak or deprecated hash algorithms (e.g., MD5, SHA-1).

Security Considerations

Signature Verification: Receivers MUST verify the JWT signature before processing any claims. Failure to verify signatures exposes the system to token forgery attacks. The signature algorithm specified in the JWT header MUST be validated against an allowlist of permitted algorithms to prevent algorithm substitution attacks.
Algorithm Allowlist: Implementations MUST maintain an allowlist of acceptable signing algorithms and MUST reject tokens signed with algorithms not on this list. The alg header parameter MUST be checked against this allowlist before signature verification. Implementations MUST NOT accept the "none" algorithm.
HTTPS Transport: It is REQUIRED that SWT transmissions occur over HTTPS to ensure the token's confidentiality and protect against man-in-the-middle attacks.
Replay Protection: The jti claim MUST be checked for uniqueness on the server side to prevent replay attacks. Each jti value MUST only be accepted once within the token's validity period. Implementations SHOULD maintain a cache or registry of seen jti values.
Expiration and Time-based Claims: Systems MUST validate the exp, nbf, and iat claims to ensure tokens are used only within their intended validity period. Implementations SHOULD allow for a small clock skew tolerance (e.g., 60 seconds) when validating time-based claims to account for clock differences between systems. Token lifetime (exp - iat) SHOULD be kept as short as practical for the use case, typically not exceeding 15 minutes for most webhook scenarios.
Key Management: Symmetric keys used for HMAC algorithms MUST be generated using a cryptographically secure random number generator and MUST have sufficient entropy (at least 256 bits for HS256). Keys SHOULD be rotated regularly. For asymmetric algorithms, private keys MUST be protected with appropriate access controls and SHOULD be stored in hardware security modules (HSMs) or key management systems (KMS) when available.
Hash Algorithm Security: When validating request body hashes, implementations MUST reject weak or deprecated hash algorithms (e.g., MD5, SHA-1). Only cryptographically strong hash algorithms (SHA-256 or stronger) SHOULD be accepted.
Respect Header Limits: Excessively large JWT tokens SHOULD be avoided to ensure compatibility with HTTP header size limits imposed by web servers and proxies.
Retry Count Validation: When the retry_count field is present, receivers SHOULD validate that its value is reasonable to prevent abuse. Implementations MAY enforce maximum retry limits (e.g., rejecting requests with retry_count exceeding a configured threshold) to protect against resource exhaustion attacks. The retry_count value MUST be a non-negative integer. Receivers SHOULD consider implementing exponential backoff expectations and MAY reject retry attempts that arrive too quickly relative to the retry_count value. Additionally, the combination of jti and retry_count should be considered together: each retry attempt MUST use a unique jti value, as retries represent distinct delivery attempts even when delivering the same event.

Interoperability Considerations SWT's use of standard HTTP POST requests with JWT-based authorization ensures broad compatibility with existing web infrastructure. The structure is simple to parse and easy to integrate with existing JWT validation libraries. The separation of token metadata and event data provides flexibility for various payload sizes and content types.

Signing and Encryption Recommendations To maintain a balance between security and usability, SWTs are RECOMMENDED to be used as JSON Web Signatures (JWS) , specifically signed JWTs. This provides data integrity and allows the recipient to verify the token's authenticity. The following signing algorithms are suggested for SWTs, as they offer a secure yet practical approach:

HS256, HS384, and HS512: Symmetric algorithms using HMAC with SHA-256, SHA-384, and SHA-512, respectively. These algorithms are considered secure and performant for most applications, especially when using shared symmetric keys between the issuer and the receiver.

While these symmetric algorithms are RECOMMENDED for ease of use and efficiency, other supported algorithms, including asymmetric methods such as RS256 (RSA with SHA-256) or ES256 (ECDSA with SHA-256), MAY also be used if needed based on security requirements or system constraints.

Encrypted JWT Support (JWE) In addition to JWS, SWT allows the use of the JSON Web Encryption (JWE) standard if encrypted JWTs are required to protect sensitive data within the token. JWE adds encryption layers to JWTs, providing confidentiality as well as integrity protection, which may be appropriate in contexts where tokens contain sensitive information.

IANA Considerations

Media Type Registration This specification registers the application/swt+jwt media type in the IANA "Media Types" registry in the manner described in . The following entries should be registered:

Type name: application
Subtype name: swt+jwt
Required parameters: n/a
Optional parameters: n/a
Encoding considerations: 8-bit; application/swt+jwt values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') characters
Security considerations: See Security Considerations section of this document
Interoperability considerations: n/a
Published specification: This document
Applications that use this media type: Webhook delivery systems, event notification platforms, and applications requiring secure webhook authentication
Fragment identifier considerations: n/a
Additional information:
- Magic number(s): n/a
- File extension(s): n/a
- Macintosh file type code(s): n/a
Person & email address to contact for further information: Stephan Knauer, mail@knauer.consulting
Intended usage: COMMON
Restrictions on usage: none
Author: Stephan Knauer, mail@knauer.consulting
Change controller: IESG
Provisional registration? No

JSON Web Token Claims Registration This document updates the IANA "JSON Web Token Claims" registry for JWT Claim Names. Following the format in , the following should be registered.

Claim Name: "webhook"
Claim Description: Webhook
Change Controller: IESG
Specification Document(s): of this document

JWT webhook claim The webhook claim is a JSON object that describes the event to be triggered and optionally includes metadata about the event data sent in the request body. It consists of the following fields:

event: A case-sensitive string describing the name of the webhook event. It should be concise and specific (e.g., "order.created").
hash (OPTIONAL): The hash algorithm and the hash digest of the request body payload (hex-encoded) (see ).
- This field MUST be present when the request body is non-empty (Content-Length > 0).
- This field SHOULD be omitted when the request body is empty (Content-Length = 0).
retry_count (OPTIONAL): A non-negative integer indicating the delivery attempt number for this webhook event.
- A value of 0 indicates the initial delivery attempt (no retry).
- A value of 1 or greater indicates a retry attempt (e.g., 1 = first retry, 2 = second retry).
- This field SHOULD be included when the webhook system implements retry logic for failed deliveries.
- Receivers MAY use this value to implement progressive backoff strategies, rate limiting, or to decide whether to accept further retries.

Implementers MAY restrict the set of supported algorithms based on their security posture.

Senders and receivers SHOULD agree on supported algorithms in advance. Although NOT RECOMMENDED, it may be necessary to send non-JSON event data via SWT. The HTTP Content-Type header SHOULD be set accordingly.

Examples of JWT webhook claim Initial delivery attempt: Retry attempt:

Validation To validate an SWT, the receiving system MUST perform the following checks:

JWT Validation: The token in the Authorization header MUST be a valid JWT with all required claims.
Webhook Claim Validation: The JWT MUST contain a webhook claim with an event field.
Body and Hash Validation:
- If the request body is non-empty (Content-Length > 0):
  - The webhook claim MUST contain a hash field.
  - The computed hash of the request body MUST match the hash value specified in the webhook claim using the specified algorithm.
- If the request body is empty (Content-Length = 0):
  - The webhook claim MUST NOT contain a hash field.

If any validation check fails, the server SHOULD respond with an appropriate HTTP error code:

401 Unauthorized: If JWT signature verification fails, the token is expired, or authentication credentials are invalid.
403 Forbidden: If the token is valid but the issuer lacks permission to trigger the webhook or access the resource.
400 Bad Request: If the request is malformed (e.g., missing required claims, invalid hash format, or hash mismatch).

Examples

Example 1: Empty body (notification only) Webhook claim: POST request:

Example 2: Non-empty body with hash Webhook claim: POST request:

Conclusion The Secure Webhook Token (SWT) format provides a secure, interoperable, and efficient solution for webhook authentication. Its focus on signed payloads, minimal overhead, and clear transport guidance makes it suitable for modern web service ecosystems.