NB: This note is part of a series of my personal notes on API Security. To understand what API Security is, please read my Introduction Note on the subject

Understanding WebHook and its Design Flaws

In this note, i'll be discussing an exciting topic that I’ve been exploring lately: webhooks. I’ve come to realize that webhooks offer a fast, simple, and efficient way to integrate remote applications through HTTP communication. However, this simplicity and efficiency come with a crucial trade-off that we must address: security.

It’s fascinating to see how webhooks streamline the process of data exchange, but I’ve also learned that they were not designed to be inherently secure. As developers, the responsibility of ensuring webhook security rests solely on our shoulders.

Some of the webhook security concerns and design flaws include:

1. Lack of Authentication and Authorization: Failing to implement proper authentication and authorization mechanisms can allow unauthorized access to your webhook endpoints and sensitive data.
2. Insecure Payloads: Not validating or sanitizing incoming webhook payloads can lead to the injection of malicious code or unexpected data, potentially compromising your application's security.
3. No Payload Validation: Ignoring payload validation opens the door to data inconsistencies, errors, and unexpected behavior that could impact your application's reliability.
4. Unprotected Data: Transmitting sensitive data in plain text without encryption exposes it to eavesdropping and interception by malicious actors.
5. Unencrypted Communication: Without using HTTPS, the communication between sender and receiver can be easily intercepted and manipulated.
6. Excessive Permissions: Assigning excessive permissions to webhook endpoints can result in unauthorized access and potential data breaches.
7. Hardcoded Callback URLs: Using hardcoded URLs instead of dynamic ones can lead to inflexibility and potential security issues when systems are migrated or updated.
8. Missing Error Handling: Neglecting error handling can result in unhandled exceptions, leading to downtime or incorrect data processing.
9. Unauthenticated Sources: Trusting incoming webhooks without proper source authentication can lead to accepting forged or spoofed requests.

Let’s delve into this further and explore the best practices and measures we can implement to safeguard our applications and data while benefiting from the remarkable capabilities of webhooks. This will be based on my personal experiences.

My Experience

I've implemented webhooks in some of the projects i've worked on, both as source and destination, one of the first things i do when implementing a webhook receiver (destination) is verifying the source (authentication). There are some common methods of authentication that established systems use for sending out webhook notifications, and as a consumer or the destination, my implementation depends on what the source has. The 3 most common methods of authentication are:

1. Basic authentication
2. Token authentication
3. Signature verification

Signature verification: Signature verification makes use of the Hash-based Message Authentication Code (HMAC) for authenticating and validating webhooks.

Below is a sample of how i handled Paystack's webhook as a destination

const secretKey = Env.get('PAYSTACK_SECRET_KEY')

//validate event
const hash = crypto
    .createHmac('sha512', secretKey)
    .update(JSON.stringify(request.body()))
    .digest('hex')
if (hash === request.request.headers['x-paystack-signature']) {
    // Retrieve the request's body
    const event = request.body()
    // Do something with event
    console.log(event)

}

Basic authentication: Basic authentication is one of the oldest, simplest ways of verifying webhooks. It makes use of a username and password for webhook producers to be authenticated when sending webhooks to an HTTP endpoint (webhook URL).

Here is another sample of my implementation, the source of this one is CoralPay, and they use basic authentication.

// verify auth credentials
if (!request.headers().authorization) {
    return response.status(401).json({
    status: 401,
    message: 'Unauthorized Access',
    })
}
const base64Credentials = request.headers().authorization!.split(' ')[1]
const credentials = Buffer.from(base64Credentials, 'base64').toString('ascii')
const [username, password] = credentials.split(':')
if (
    username !== Env.get('CORALPAY_VERGE_USERNAME') ||
    password !== Env.get('CORALPAY_VERGE_PASSWORD')
) {
    return response.status(403).json({
    status: 403,
    message: 'Forbidden Access',
    })
}

Useful Resources

• WebHook Security 101
• Webhook Authentication Strategies