Securing Webhooks/Listener API Requests

You can set up event driven alerts that send a payload of information to your backend using Flatfile's event listener. You may want to secure these requests, and there are several options for doing so!

1. Using Webhook Signatures

A webhook signature is essentially a hash of the payload that is sent along with the request. This signature helps the receiving server verify that the message comes from the expected sender and that it hasn't been altered during transit. Here’s how you can implement it:

Generate a Signature: The sending server generates a signature by creating a hash of the payload using a secret key. This hash can be created using standard cryptographic algorithms like HMAC-SHA256.
Transmit the Signature: The signature is typically sent as part of the HTTP headers. For instance, it could be included as X-Hub-Signature in the headers.
Verify the Signature: Upon receiving the webhook, the receiving server can use the same secret key to generate a hash of the incoming payload and compare it to the signature provided in the header. If they match, it confirms that the payload has not been tampered with and that it comes from a trusted source.

2. Creating JWT in the Listener

JWTs are an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. Here’s how JWT can be utilized for securing webhooks:

Generate a JWT: The sender generates a JWT which includes claims about the webhook event and signs it using a secret key. This token encapsulates and securely transmits information.
Pass JWT in Header: The JWT is then passed as a part of the HTTP headers. For example, it can be included in the Authorization header as a Bearer token.
Verify JWT on Reception: The receiving server then validates the JWT using the secret key. This validation checks the signature to ensure the token hasn't been altered and confirms the sender’s identity.

Here is a sample code snippet that demonstrates how to send a POST request with JWT in the headers using the Axios library:

const axios = require('axios'); 
const jwt = require('jsonwebtoken'); 

const payload = {
 // Your payload data 
}; 
const secret = 'your-very-secret-key'; 
const token = jwt.sign(payload, secret); 

const response = await axios.post(
 'https://your-webhook-url.com',
 {...payload},
 { headers:
  { 
   "Content-Type": "application/json",
   "Authorization": `Bearer ${token}`
  },
 } 
);

Best Practices for Securing Webhooks

In addition to using webhook signatures and JWTs, consider the following practices to secure your webhooks or event-driven alerts:

Use HTTPS: Always use HTTPS to encrypt the transmission of data and headers.
Validate Input: Always validate and sanitize any input received through webhooks to avoid injection attacks.
Limit IP Addresses: If possible, limit incoming webhook requests to known IP addresses.

By implementing these security measures, you can significantly reduce the risk of unauthorized access and ensure that you can provide a reliable and secure communication channel between applications.