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 16 November 2025.¶

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 either HTTP HEAD or HTTP POST requests (See Section 9.3.1 of [RFC9110]), ensuring minimal data exposure and optimal compatibility with typical HTTP implementations.¶

2. Secure Webhook Token (SWT) Overview

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

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

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

5. JWT Structure

An SWT comprises the following:¶

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

{
  "webhook": {
    "event": "delivery.scheduled",
    "data": {
      "carrier": "UPS",
      "scheduledDeliveryDate": "2024-12-24T12:24Z",
      "recipient": {
        "name": "Lucky Kid",
        "address": {
          "locality": "Somewhere",
          "postalCode": "0815",
          "street": "Happy Place 1"
        },
        "sender": {
          "name": "Santa Claus",
          "address": {
            "locality": "North Pole",
            "postalCode": "88888",
            "street": "123 Elf Road"
          }
        }
      }
    }
  },
  "exp": 1733987961,
  "nbf": 1733987661,
  "iat": 1733987661,
  "iss": "swt.example.com",
  "jti": "2020B14D-C365-4BCF-84CD-5D423E0C6687"
}

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

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

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

9. IANA Considerations

This document updates the IANA "JSON Web Token Claims" registry for JWT Claim Names. Following the format in Section 10.1.1 of [RFC7519], the following should be registered.¶

• Claim Name: "webhook"¶
• Claim Description: Webhook¶
• Change Controller: IESG¶
• Specification Document(s): Section 9.1¶

"webhook": {
  "event": "delivery.scheduled",
  "data": {
    "carrier": "UPS",
    "scheduledDeliveryDate": "2024-12-24T12:24Z",
    "recipient": {
      "name": "Lucky Kid",
      "address": {
        "locality": "Somewhere",
        "postalCode": "0815",
        "street": "Happy Place 1"
      },
      "sender": {
        "name": "Santa Claus",
        "address": {
          "locality": "North Pole",
          "postalCode": "88888",
          "street": "123 Elf Road"
        }
      }
    }
  }
}

"webhook": {
  "event": "issue.opened",
  "data": {
    "hash": "ab6e46d9c488...",
    "hashAlg": "sha3-256",
    "size": 6123
  }
}

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

 {
  "webhook": {
    "event": "delivery.scheduled",
    "data": {
      "carrier": "UPS",
      "scheduledDeliveryDate": "2024-12-24T12:24Z",
      "recipient": {
        "name": "Lucky Kid",
        "address": {
          "locality": "Somewhere",
          "postalCode": "0815",
          "street": "Happy Place 1"
        },
        "sender": {
          "name": "Santa Claus",
          "address": {
            "locality": "North Pole",
            "postalCode": "88888",
            "street": "123 Elf Road"
          }
        }
      }
    }
  }
}

HEAD / HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV...
Host: localhost

{
  "webhook": {
    "event": "issue.opened",
    "data": {
      "hash": "ab6e46d9c488...",
      "size": 6123
    }
  }
}

POST / HTTP/1.1
Content-Length: 6123
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJK...
Host: localhost

{
   "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,
     ...
   }
 }

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