Secure Webhook Token (SWT)
Leipzig, SN Germany mail@knauer.consulting
Internet Network Working Group The Secure Webhook Token (SWT) is a specialized JSON Web Token (JWT) format designed for securely authorizing and verifying webhook requests. It defines a set of claims to ensure that the token is explicitly tied to webhook events and that its integrity can be reliably validated by the recipient. A key feature of SWT is the introduction of a unique claim, webhook, which encapsulates webhook-specific information, such as the event type. By providing a structured and secure approach to webhook authentication, SWT aims to be a lightweight and flexible solution while maintaining compatibility with typical JWT structures. It is designed with the best practices in mind and may serve as a foundation for future standardization efforts.
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 either HTTP HEAD or HTTP POST requests (See ), ensuring minimal data exposure 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, prescribes the transport protocol as HTTP HEAD (RECOMMENDED) or HTTP POST, and suggests a maximum payload size of 6kB for HEAD requests to remain efficient and compatible with the widely used default 8kB HTTP header size limit. These constraints ensure interoperability across diverse systems and help prevent issues on servers with unmodified configurations. To support larger payloads or non-JSON content, HTTP POST can be used as an alternative transport method, allowing the event data to be sent in the request body.
Transport Requirements SWTs must be transmitted via HTTP HEAD OR POST requests only. The HEAD method MUST be used if the event data size is less than or equal to 6kB and contains valid JSON. Otherwise, the POST method MUST be used. SWTs MUST be transmitted using either HTTP HEAD or HTTP POST requests.
  • The HEAD method SHOULD be used when the event data is valid JSON and the total header size is reasonably small (e.g., <= 6kB). This is based on the default 8kB header size limit enforced by many web servers.
  • The POST method MUST be used for larger payloads, non-JSON data, or when the header size exceeds what is supported by the server.
Note: There is no hard limit on the size of a HEAD request, but practical constraints exist. For example, implementations such as Go's http.Server allow configurable limits (e.g., up to 1MB headers), though such configurations should be applied cautiously due to security considerations.
Token Size Limitation Recommended Maximum Token Size: While there is no strict maximum size for an SWT, a recommended size limit of 6kB is proposed for the event data, so that the total size of the SWT is less than 8KB, which is the default max header size of most existing HTTP servers. This is based on the primary use case for SWTs, which is to securely authorize and trigger events rather than transmit extensive data. The token SHOULD be kept concise, containing only essential claims to support efficient processing and minimize resource usage. Header Size Considerations: In practice, many web servers impose a default maximum HTTP header size of 8KB. If servers are not configured to allow larger headers, exceeding this size MAY lead to transmission errors or dropped requests. However, maintaining a compact token design aligns with this specification's intent to facilitate secure and lightweight webhook interactions.
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 "JWT".
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.
    • data (OPTIONAL): Describes the webhook data itself, which is related to the aforementioned event.
  • 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 an event only:
SWT payload with event and data:
Security Considerations
  1. HTTPS Transport: It is RECOMMENDED that SWT transmissions occur over HTTPS to ensure the token's confidentiality.
  2. Replay Protection: The jti claim SHOULD be checked for uniqueness on the server side to prevent replay attacks. Each jti value SHOULD only be accepted once.
  3. Expiration Enforcement: Systems MUST validate the exp claim to ensure that tokens cannot be used beyond their intended validity.
  4. Respect Header Limits: Excessively large headers SHOULD be avoided. HEAD method is ideal for compact, JSON-only payloads.
Interoperability Considerations SWT's RECOMMENDED 6kB size target and support for both HEAD and POST methods ensure broad compatibility. The structure is simple to parse and easy to integrate with existing JWT validation libraries.
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 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):
JWT webhook claim The webhook claim is a JSON object that describes the event to be triggered and, optionally, the data related to that event. 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").
  • data (OPTIONAL): Describes the event data. The handling of this field depends on the transport method used (HEAD or POST):
Although NOT RECOMMENDED, it may be necessary to send non-JSON event data via SWT. The HTTP Content-Type header SHOULD be set accordingly if using the POST method.
Case 1: HTTP HEAD Requests If the event data is valid JSON and small (<= 6kB), it MAY be included inline in the data field of the JWT. In this case:
  • Use of data is OPTIONAL.
  • Sending "data": null is equivalent to omitting the field.
  • This is the RECOMMENDED case, as it minimizes complexity and improves performance.
Case 2: HTTP POST Requests For larger payloads or non-JSON content types, the data MUST be sent in the POST request body. The data field in the JWT's webhook claim must contain a descriptor object with the following fields:
  • hash: The hash digest of the body payload (base64- or hex-encoded).
  • size: The exact byte size of the event data to be sent in the request body.
  • hashAlg (RECOMMENDED): The algorithm used to compute the hash. If omitted, the default SHOULD be assumed to be sha3-256.
Supported hashAlg values: The hashAlg value MUST be one of the following:
  • sha256
  • sha384
  • sha512
  • sha3-256
  • sha3-384
  • sha3-512
Implementers MAY restrict the set of supported algorithms based on their security posture.
If hashAlg is omitted, receivers SHOULD assume the use of sha3-256 by default. Senders and receivers SHOULD agree on supported algorithms in advance.
Example of JWT webhook claim for HEAD Method
Example of JWT webhook claim for POST Method
Validation To validate an SWT, the receiving system MUST distinguish between the HTTP method used (HEAD or POST):
  1. HTTP HEAD method. Sending an SWT via HTTP HEAD method, the received SWT is valid only if the JWT itself is valid.
  2. HTTP POST method. Sending an SWT via HTTP POST method, the received SWT MUST be a valid JWT and contain the webhook claim with the hash and size values of event data to be sent in the body. If either the size or the hash of the payload is different from the ones specified within the SWT webhook claim then it MUST be rejected.
If validation fails, the server SHOULD respond with a 400 Bad Request or 403 Forbidden, depending on the context.
Examples:
Case 1: Data size is smaller <= 6kB and is sent via HTTP-HEAD request directly with additional data Webhook claim: HEAD request:
Case 2: Data size is > 6kB send the JWT webhook claim MUST contain only "hash" and "size" values of the data to be sent. The actual data is send in the POST request body. 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.
References Normative References Informative References