Freshworks

deepak12f@gmail.com

httpapi PCRP This document defines the PCRP (Ping, Challenge, Resolve, Product) Specification for Webhook events in a standardized way. It is specifically designed to address the challenges faced in current webhook event implementations, which lack consistency and a defined flow. PCRP introduces a new header X-PCRP-Type to indicate the step of the process, and its values include ping, challenge, resolve, and product.

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.

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.

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.

Detailed Specification Description

Ping Stage The first step in the PCRP process is the "ping" stage. This stage is initiated by the sender to check if the receiver is ready to process the upcoming events. The header X-PCRP-Type: ping indicates that this is a ping message. The body of the ping message may contain additional metadata for the receiver but is generally minimal. The receiver is expected to respond with a 200 OK status if it is ready to proceed to the next stage.

Challenge Stage The challenge stage is triggered when the receiver needs additional information or validation from the sender. The message will contain the header X-PCRP-Type: challenge, and the body will describe what is required from the sender (such as a CAPTCHA, token validation, or a challenge question). The sender must respond with the appropriate data in the form of a response body. If the challenge is not met or is invalid, an error message should be returned, such as a 400 Bad Request.

Resolve Stage The resolve stage is where the system provides the results or answers that were requested during the challenge stage. This stage includes the X-PCRP-Type: resolve header, and the body will contain the resolved information or status. The receiver is expected to confirm the result or take the next action accordingly. If the response is not acceptable, the system should return a 400 Bad Request or 404 Not Found status as appropriate.

Product Event Stage The final stage is the "product" event, which is sent to indicate that the event flow has completed successfully. The header X-PCRP-Type: product indicates that the system has completed the requested operation. The body will typically contain the product event data or confirmation that the task has been successfully completed. The receiver may perform any necessary follow-up actions at this stage. The response should generally be 200 OK to confirm that the process has been successfully completed.

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.

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.

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.

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.

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.

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.

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