PCRP Webhook Specification

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 26 June 2025.¶

Copyright Notice

Copyright (c) 2024 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

Webhooks are widely used to facilitate communication between systems, but the lack of industry standards for their event flow and error handling poses challenges for developers. Existing webhook implementations often vary significantly between services, leading to potential issues in reliability, debugging, and integration with multiple systems. This draft proposes a new webhook event standard, PCRP, which introduces structured steps for webhooks: Ping, Challenge, Resolve, and Product. This standard ensures predictable behavior and simplifies handling on both the sender and receiver sides.¶

The primary goal of PCRP is to standardize the webhook event lifecycle, reducing ambiguity, improving error handling, and offering a predictable structure for developers to follow. This will help developers address common pain points when integrating webhook events and will lay the foundation for future webhook standards.¶

2. Specification Overview

PCRP introduces a new set of headers for webhook events. The core header is `X-PCRP-Type`, which indicates the step of the process. The four defined types are:¶

• ping: A message used to initiate the event flow.¶
• challenge: A request for confirmation or validation.¶
• resolve: A message indicating resolution of the challenge, often providing the results or response.¶
• product: The final event indicating the product event stage, with any relevant data or status.¶

3. Key Features

• Predictability: Each step of the event flow has a clearly defined purpose.¶
• Consistency: All webhook event handlers know exactly how to handle each of the four event stages.¶
• Error Handling: Each event stage can have clearly defined error responses, improving debuggability.¶
• Flexibility: While PCRP defines the general structure, it allows flexibility for each stage to carry additional data as needed.¶

4. Detailed Specification Description

5. Header Details

• X-PCRP-Type Role: Specifies the current step in the PCRP spec. Responsibility: Defines the current stage of the transaction. It helps the receiver understand which phase the request is part of. Values: ping, challenge, resolve, product¶
• X-PCRP-Transaction-ID Role: Identifies a specific transaction or event flow across all stages. Responsibility: Remains the same throughout the entire event lifecycle, ensuring continuity for tracking and correlating all stages of a transaction. Usage: The same Transaction ID is included in the headers of all stages of the spec.¶
• X-PCRP-Nonce Role: Prevents replay attacks by ensuring the freshness of each request. Responsibility: Generates a unique nonce for each request to prevent malicious reuse in replay attacks. The receiver should verify the freshness and reject duplicates. Usage: Different nonces are used at each stage of the transaction to ensure each request is unique.¶
• X-PCRP-Signature Role: Ensures the integrity and authenticity of the Challenge message. Responsibility: Included in the Challenge request to protect the integrity of data. The signature is validated using a public key, ensuring that the message hasn't been tampered with. Usage: Only included in the Challenge stage to secure the Challenge Event.¶
• X-PCRP-Timestamp Role: Marks the exact time when the message was sent. Responsibility: Used to mitigate issues related to time-sensitive actions. Ensures that requests cannot be replayed or processed after expiration. Usage: A timestamp is included in each message (Ping, Challenge, Resolve, and Product).¶
• X-PCRP-Version Role: Specifies the version of the PCRP spec. Responsibility: Ensures compatibility between sender and receiver by allowing version checks. Outdated versions can be rejected. Usage: Specified in each header to ensure backward compatibility with future versions of PCRP.¶
• X-PCRP-Timeout Role: Specifies the maximum duration allowed for the receiver to respond. Responsibility: Defines the time limit for the receiver to process the Challenge request. If exceeded, a 408 Request Timeout response is sent. Usage: Included in the Challenge request to enforce time limits for response.¶
• X-PCRP-Rate-Limit Role: Specifies the maximum number of requests allowed within a time period. Responsibility: Informs the Producer about the rate-limiting threshold enforced by the Receiver. Usage: Included in the response headers of all stages to regulate request rate (Ping, Challenge, Resolve, Product).¶
• X-PCRP-Rate-Limit-Remaining Role: Indicates the remaining number of requests the Producer can make before hitting the rate limit. Responsibility: Helps both Producer and Receiver track how much capacity remains before the rate limit is reached. Usage: Included in the responses to indicate remaining requests allowed within the time window.¶
• X-PCRP-Rate-Limit-Reset Role: Indicates the timestamp when the rate limit will reset. Responsibility: Helps the Producer know when the rate limit quota will be replenished, allowing them to resume sending requests. Usage: Included in responses to inform the Producer when to resume making requests.¶

6. Error Handling

Each stage in the PCRP specification should provide clear error handling instructions if the flow is disrupted. Depending on the stage, responses might include:¶

• 400 Bad Request: Used if the sender’s input is invalid or incomplete, or if the challenge stage is not resolved correctly.¶
• 404 Not Found: Used if a requested resource is not found or cannot be resolved during the process.¶
• 500 Internal Server Error: Indicates that an unexpected server error occurred during any stage of the process.¶

7. Common Questions

• Why is the X-PCRP-Type header necessary? The X-PCRP-Type header specifies the current stage of the transaction (Ping, Challenge, Resolve, or Product). It ensures that the receiver can correctly identify and handle the step in the protocol, maintaining the integrity of the process.¶
• Can the X-PCRP-Transaction-ID vary between stages? No, the X-PCRP-Transaction-ID must remain consistent throughout all stages (Ping, Challenge, Resolve, and Product) of a transaction. This ensures proper tracking and correlation of the event flow.¶
• How does X-PCRP-Nonce protect against replay attacks? The X-PCRP-Nonce is a unique value created for each request. It prevents replay attacks by ensuring that each request is distinct. The receiver validates the freshness of the nonce and rejects duplicate or reused values.¶
• In which stage is the X-PCRP-Signature required? The X-PCRP-Signature is required in the Challenge stage. It safeguards the integrity and authenticity of the Challenge message, confirming that it is untampered and originates from the verified sender.¶
• What if the X-PCRP-Transaction-ID is missing or incorrect? If the X-PCRP-Transaction-ID is missing or incorrect, the receiver cannot correlate the message to the transaction. This may result in errors or rejection of the request, as the continuity of the event flow is compromised.¶
• How does the X-PCRP-Timestamp prevent time-based attacks? The X-PCRP-Timestamp ensures messages are timely by marking the exact moment they are sent. The receiver verifies that the timestamp falls within an acceptable window, rejecting stale or outdated requests.¶
• Is the X-PCRP-Version header mandatory? Yes, the X-PCRP-Version header is mandatory. It ensures compatibility by confirming that both sender and receiver are using the same version of the spec. Incompatibilities may lead to rejection of the request.¶
• What happens if the X-PCRP-Nonce has already been used? If the X-PCRP-Nonce is reused, the receiver should reject the request to prevent replay attacks. The nonce guarantees each request is unique and secure.¶
• Can the same X-PCRP-Nonce be reused across requests? No, the X-PCRP-Nonce must be unique for every request within a transaction. Reusing a nonce undermines the security of the protocol and exposes it to potential attacks.¶
• What format should the X-PCRP-Signature follow? The X-PCRP-Signature is generated using cryptographic algorithms (e.g., RSA, HMAC) to sign the Challenge message. This ensures the message’s integrity and authenticity, confirming it was not altered and originated from the authorized sender.¶

8. Security Considerations

Webhooks, including those using PCRP, must be transmitted over secure channels (e.g., HTTPS) to ensure data privacy and integrity. Additionally, authentication mechanisms such as tokens or signatures should be used to verify the sender’s identity and protect against malicious actors.¶

9. IANA Considerations

The IANA should maintain a registry for the values of X-PCRP-Type to ensure no collisions with other protocols. The values defined in this document should be registered as part of this registry.¶

Appendix A. Acknowledgments

Special thanks to my teammate Bharani Shanmugam, who helped shape the PCRP specification, including experts in webhook design and implementation. Additionally, I would like to acknowledge Martin Fowler's work on microservices and transactional integrity, which inspired the design of PCRP's structured communication headers and the focus on maintaining transaction integrity across distributed systems.¶

Appendix B. References

[RFC791] Internet Protocol, Jon Postel. Date: September 1981.¶

Author's Address