Secure Webhook Token (SWT)

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 15 May 2026.¶

Copyright Notice

Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. 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 [RFC7519] structure, which includes unique claims tailored for webhook events. This specification mandates that all tokens must be transmitted using HTTP POST requests (see Section 9.3.3 of [RFC9110]), with the token in the Authorization header and event data in the request body, ensuring secure transmission and optimal compatibility with typical HTTP implementations.¶

2. Secure Webhook Token (SWT) Overview

This specification defines required claims within the JWT [RFC7519] 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.¶

3. 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.¶

4. 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).¶

5. JWT Structure

An SWT comprises the following:¶

{
  "alg": "HS256",
  "typ": "SWT"
}

{
  "webhook": {
    "event": "ping"
  },
  "exp": 1733987961,
  "nbf": 1733987661,
  "iat": 1733987661,
  "iss": "swt.example.com",
  "jti": "2020B14D-C365-4BCF-84CD-5D423E0C6687"
}

{
  "webhook": {
    "event": "delivery.scheduled",
    "hash": "sha-256:22b793b7c031e6a3...05ba920b",
    "retry_count": 0
  },
  "exp": 1733987961,
  "nbf": 1733987661,
  "iat": 1733987661,
  "iss": "swt.example.com",
  "jti": "2020B14D-C365-4BCF-84CD-5D423E0C6687"
}

{
  "webhook": {
    "event": "delivery.scheduled",
    "hash": "sha-256:22b793b7c031e6a3...05ba920b",
    "retry_count": 3
  },
  "exp": 1733988561,
  "nbf": 1733988261,
  "iat": 1733988261,
  "iss": "swt.example.com",
  "jti": "A1C3F89E-2F4D-4A8C-9B2E-7D8F1C3E5A9B"
}

6. Request Body Integrity

"webhook": {
  "event": "delivery.scheduled",
  "hash": "sha-512:f8f24b01df358f10...df03db5cf"
}

  "hash": "sha-256:04ef96c3bc56b3c4...200a5353"
  "hash": "sha-512:f8f24b01df358f10...df03db5cf"

[algo, value] = hash.split(":")

7. Security Considerations

1. 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.¶

2. 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.¶

3. 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.¶

4. 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.¶

5. 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.¶

6. 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.¶

7. 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.¶

8. Respect Header Limits: Excessively large JWT tokens SHOULD be avoided to ensure compatibility with HTTP header size limits imposed by web servers and proxies.¶

9. 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.¶

8. 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.¶

9. Signing and Encryption Recommendations

To maintain a balance between security and usability, SWTs are RECOMMENDED to be used as JSON Web Signatures (JWS) [RFC7515], 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.¶

10. IANA Considerations

"webhook": {
  "event": "issue.opened",
  "hash": "sha-256:04ef96c3bc56b3c4...200a5353",
  "retry_count": 0
}

"webhook": {
  "event": "issue.opened",
  "hash": "sha-256:04ef96c3bc56b3c4...200a5353",
  "retry_count": 2
}

11. Validation

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

1. JWT Validation: The token in the Authorization header MUST be a valid JWT with all required claims.¶
2. Webhook Claim Validation: The JWT MUST contain a webhook claim with an event field.¶

3. 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).¶

{
  "webhook": {
    "event": "ping"
  },
  "exp": 1733987961,
  "nbf": 1733987661,
  "iat": 1733987661,
  "iss": "swt.example.com",
  "jti": "2020B14D-C365-4BCF-84CD-5D423E0C6687"
}

POST /webhook HTTP/1.1
Content-Length: 0
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Host: example.com

{
  "webhook": {
    "event": "issue.opened",
    "hash": "sha-256:04ef96c3bc56b3c4...200a5353",
    "retry_count": 0
  },
  "exp": 1733987961,
  "nbf": 1733987661,
  "iat": 1733987661,
  "iss": "swt.example.com",
  "jti": "2020B14D-C365-4BCF-84CD-5D423E0C6687"
}

POST /webhook HTTP/1.1
Content-Length: 6123
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Host: example.com

{
   "action": "opened",
   "issue": {
     "url": "https://api.github.com/repos/octocat/...",
     "number": 1347,
     ...
   },
   "repository" : {
     "id": 1296269,
     "full_name": "octocat/Hello-World",
     "owner": {
       "login": "octocat",
       "id": 1,
       ...
     },
     ...
   },
   "sender": {
     "login": "octocat",
     "id": 1,
     ...
   }
 }

12. 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.¶

Author's Address