httpapi                                                     D. Arumugham
Internet-Draft                                                Freshworks
Intended status: Standards Track                        23 December 2024
Expires: 26 June 2025


                       PCRP Webhook Specification
                   draft-deepakarumugham-pcrp-spec-00

Abstract

   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.

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.











Arumugham                 Expires 26 June 2025                  [Page 1]

Internet-Draft         PCRP Webhook Specification          December 2024


   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  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Specification Overview  . . . . . . . . . . . . . . . . . . .   3
   3.  Key Features  . . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  Detailed Specification Description  . . . . . . . . . . . . .   3
     4.1.  Ping Stage  . . . . . . . . . . . . . . . . . . . . . . .   3
     4.2.  Challenge Stage . . . . . . . . . . . . . . . . . . . . .   4
     4.3.  Resolve Stage . . . . . . . . . . . . . . . . . . . . . .   4
     4.4.  Product Event Stage . . . . . . . . . . . . . . . . . . .   4
   5.  Header Details  . . . . . . . . . . . . . . . . . . . . . . .   4
   6.  Error Handling  . . . . . . . . . . . . . . . . . . . . . . .   6
   7.  Common Questions  . . . . . . . . . . . . . . . . . . . . . .   6
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
   Appendix A.  Acknowledgments  . . . . . . . . . . . . . . . . . .   8
   Appendix B.  References . . . . . . . . . . . . . . . . . . . . .   8
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   8

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.





Arumugham                 Expires 26 June 2025                  [Page 2]

Internet-Draft         PCRP Webhook Specification          December 2024


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

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








Arumugham                 Expires 26 June 2025                  [Page 3]

Internet-Draft         PCRP Webhook Specification          December 2024


4.2.  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*.

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

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

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









Arumugham                 Expires 26 June 2025                  [Page 4]

Internet-Draft         PCRP Webhook Specification          December 2024


   *  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



Arumugham                 Expires 26 June 2025                  [Page 5]

Internet-Draft         PCRP Webhook Specification          December 2024


      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.



Arumugham                 Expires 26 June 2025                  [Page 6]

Internet-Draft         PCRP Webhook Specification          December 2024


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





Arumugham                 Expires 26 June 2025                  [Page 7]

Internet-Draft         PCRP Webhook Specification          December 2024


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

   Deepak Arumugham
   Freshworks
   Email: deepak12f@gmail.com
































Arumugham                 Expires 26 June 2025                  [Page 8]