DOCSEARCHbyAlgolia
Submit Docs

webhooks.fyi

website·Indexed 34 days ago

https://webhooks.fyi

A comprehensive resource and directory for webhooks, providing guidance on security implementations (HMAC, asymmetric key signatures, JWT, shared secrets), operational best practices for resiliency and versioning, and a directory of technical specifications for providers like Stripe, GitHub, Slack, Twilio, and Zoom.

Tokens
10.2K
Snippets
17
Records
88
Agent score
72%

What's inside webhooks.fyi

  1. Overview of webhooks.fyi resources

    webhooks.fyi is a comprehensive resource for developers building or consuming webhooks. It provides a directory of webhook providers and guidance on industry standards across three main pillars: security, operational experience, and implementation best practices for both providers and consumers.

  2. Best practices for writing webhook documentation

    To ensure a positive developer and operator experience, webhook documentation should be comprehensive and self-contained. Essential components include:

    • Context: An overview of when to use webhooks.
    • Event Catalog: A full list of supported events and instructions on how to subscribe to them.
    • Verification: Clear instructions for one-time verification checks (if applicable).
    • Security: A comprehensive list of security features, human-friendly explanations of how security controls work, and specific payload instructions for hash signatures.
    • Implementation Path: A step-by-step journey for receiving, validating, and processing events.
    • Technical Specs: Example payloads, complete sample code, and explicit details on encoding formats (e.g., base64 vs hex) and signature date formats (e.g., Unix vs RFC 3339).
    • Operations: Guidance on handling lost messages and retry mechanisms.
    • Network Control: Information for compensatory controls, such as a list of IP addresses for firewall allowlisting.

  3. Understand how webhooks enable system notifications

    Webhooks are a programming language agnostic method for one system to notify another system of a state change. Unlike polling, where a downstream system repeatedly asks a central system for updates, webhooks use a notification-based approach where the central system broadcasts an event to the listener.

    In practical implementation, a webhook is an HTTP request (typically a POST or GET) containing a JSON payload or parameters. This allows distributed systems to communicate regardless of their specific tech stack, vendor, or network location. Common use cases include receiving notifications for successful payments in Stripe, new incidents in PagerDuty, or incoming SMS via Twilio.

  4. Validate webhook authenticity during runtime

    To ensure that webhook notifications are authentic, have not been tampered with, and are not replay attacks, providers implement runtime security controls. Common methods for runtime validation include:

    • Shared Secrets, Basic Authentication, Bearer Tokens, and Verification tokens
    • Hash-based Message Authentication Code (HMAC)
    • Asymmetric Key Signatures
    • JWTs, JWKs, and OAuth 2.0
    • Mutual TLS Authentication (mTLS)
    • Replay Prevention mechanisms

  5. Submit a patch or fix mistakes in webhooks.fyi

    If you find documentation errors or need to apply a patch to webhooks.fyi, follow these steps:

    1. Clone the repository from GitHub.
    2. Deploy the project locally using the instructions in the README.md file.
    3. Apply changes (typically within markdown files under /src/pages/).
    4. Verify that the pages render correctly.
    5. Submit a pull request including links to the relevant source documentation for verification.

    Alternatively, you can file a GitHub issue to report a mistake, provided you include a link to the provider's documentation.

  6. Implement compensatory controls for webhook listeners

    Webhook consumers (listeners) can implement additional compensatory controls to increase the security of the communication channel. Examples of these controls include restricting incoming requests to specific IP addresses or implementing API callbacks to the webhook service to verify events.

  7. Implement HMAC signature validation for webhooks

    Hash-based Message Authentication Code (HMAC) is used to verify the authenticity and integrity of a webhook request. The provider signs the payload using a secret key and a hashing algorithm (typically HMAC-SHA256), sending the resulting signature in a request header. The listener must repeat this process using the same secret key and compare the resulting signature with the one provided in the header. To prevent timing attacks, use a constant-time comparison function like crypto.timingSafeEqual.
    const signatureHeader = 'Signature-Header'
const signatureAlgorithm = 'sha256'
const encodeFormat = 'hex'
const hmacSecret = process.env.WEBHOOK_SECRET

app.post('/webhook', (req, res) => {
  // Create digest with payload + hmac secret
  const hashPayload = req.rawBody
  const hmac = crypto.createHmac(signatureAlgorithm, hmacSecret)
  const digest = Buffer.from(signatureAlgorithm + '=' + hmac.update(hashPayload).digest(encodeFormat), 'utf8')
    
  // Get hash sent by the provider
  const providerSig = Buffer.from(req.get(signatureHeader) || '', 'utf8')
  
  // Compare digest signature with signature sent by provider using timingSafeEqual
  if (providerSig.length !== digest.length || !crypto.timingSafeEqual(digest, providerSig)) {
    res.status(401).send('Unauthorized')
  } else {
    // Webhook Authenticated
    res.json({ message: "Success" })
  }
})

  8. Implement webhook versioning for forward compatibility

    To evolve webhook messaging, features, and security without breaking legacy endpoints, providers should include version information in the webhook request. This allows consumers to identify the payload format and signature method being used, enabling a gradual migration to newer versions. Versioning can be applied globally or on a per-event basis to reduce migration complexity.

  9. Authenticate webhooks using a Shared Secret

    Shared Secret authentication involves the webhook provider and listener sharing a common secret (such as Basic Auth credentials, a bearer token, or a verification token). The provider includes this secret in a pre-defined header or the Authorization header of the request. The listener then validates this value against its own stored secret before processing the request. This method provides low-complexity authentication but does not ensure message integrity or confidentiality.
    app.post('/webhook', (req, res) => {
  // get authorization header (Basic <value>)
  const b64auth = (req.headers.authorization || '').split('Basic ')[1] || ''
  // Get login and password
  const [login, password] = Buffer.from(b64auth, 'base64').toString().split(':')
  // Verify login and password are correct
  if (login && password && 
      login === process.env.WEBHOOK_LOGIN && 
      password === process.env.WEBHOOK_PW) {
    // Webhook Authenticated
    // process and respond...
    res.json({ message: "Success" })
  } else {
    res.status(401).send('Authentication required.')
  }
})

  10. Implement the Standard Webhooks specification

    The Standard Webhooks specification provides a set of conventions for webhook producers (senders) to ensure a secure, consistent, and interoperable interface for consumers (receivers). It defines both mandatory requirements for compatibility and recommended practices to improve the integration experience for both parties.

  11. Implement dataless webhook notifications for increased security

    Dataless notifications are a webhook pattern where the provider sends a minimal payload signaling that an event occurred, rather than including the actual confidential data. This reduces the risk of data breaches and lowers security requirements for the webhook delivery mechanism.

    When a consumer receives a dataless notification, they must use a separate API call (requiring an API key) to the provider to retrieve the full event details.

    Pros:

    • Prevents confidential data from being transmitted via webhook.
    • Reduces security requirements for the webhook endpoint.
    • Can reduce request traffic if bulk operations are used to fetch data.

    Caveats:

    • Consumers must implement logic to call the provider's API.
    • Requires management and distribution of API keys to consumers.
    • Introduces dependencies on the provider's REST API performance and rate limits.
    // Example of a dataless payload (similar to Microsoft OneNote)
{
  "value": [
    {
      "subscriptionId": "A640DFF3-0429-44FC-AF7E-30523A476864",
      "expirationDateTime": "2017-02-22T16:00:00Z",
      "resource": "/me/drive/root",
      "clientState": "client-specific string"
    }
  ]
}

  12. Implement webhook verification using asymmetric key signatures

    Asymmetric key signatures use a public/private key pair to secure webhooks. The provider signs the request with a private key, and the listener validates it using a corresponding public key. This provides non-repudiation, ensuring that only the holder of the private key (the provider) could have sent the message.

    Verification Process:

    1. The provider signs the webhook message with its private key and includes the signature in a request header.
    2. The listener receives the request and uses a verifier (such as EdDSA, ECDSA, or RSA) with the public key, the request body, and the signature header.
    3. If the verifier returns positive, the request is considered legitimate.

    Commonly used algorithms include EdDSA, ECDSA, and RSA.