Webhooks are a powerful tool for integrating different systems and sending notifications in real time. They allow one application to automatically notify another when an event occurs, without the need for constant requests to check if there is something new, as happens in a traditional API. In this post, we will understand how they work, how to configure them and we will explore a practical example using the Webhook.site tool, which facilitates the development and testing of webhooks.

What Are Webhooks?

In simple terms, a webhook is a mechanism that allows a service to send an HTTP request to a specific URL whenever an event occurs. Instead of needing to query a server repeatedly to check for changes (as happens when using an API), the webhook notifies your application as soon as the event occurs. This saves time and resources, making interactions between systems more efficient.

A classic example of the use of webhooks is in payment services: when a transaction is completed, the system sends a webhook to your application informing you of the payment status. From there, your application can process this information, such as updating the status of an order, sending a receipt via email, among other actions.

How Do Webhooks Work?

1. Webhook Configuration: You register a URL to receive notifications. This URL will be called every time a relevant event happens on the service sending the webhook.

2. Event Occurring: When the configured event (such as a transaction, data update, or creation of a record) occurs, the service triggers an HTTP request to the registered URL.

3. Webhook Processing: Your application receives this request and processes the information. For example, you can update data in the database, send a response to the user, or perform any other necessary task.

4. Request Response: After processing the webhook, your application must respond with an HTTP status code (such as 200 OK) to inform you that the request was received and processed correctly.

Practical Example with Webhook.site

Before configuring webhooks in a real application, it is a good practice to test them locally or in a development environment. An excellent tool for this is Webhook.site. It provides a temporary URL where you can submit webhooks to preview and debug them, allowing you to see exactly how the data is received.

Let's use Webhook.site to test reception of a webhook.

1. Accessing Webhook.site:

   • Go to Webhook.site.
   • The site automatically generates a unique URL for you (something like https://webhook.site/unique-url). This will be the URL we will use to receive notifications.

2. Configuring Webhook Sending:

   • Imagine you have a system that triggers webhooks. Configure this system to send requests to the URL provided by Webhook.site.
   • If you want to test locally, you can simulate sending webhooks using tools like cURL or Postman, sending requests to the generated URL.

Now, let's implement some Node.js code that simulates sending a webhook to this URL.

Webhook Implementation Example in Node.js

Here is an example of how to configure an endpoint to receive webhooks and how to send a webhook using axios (or any other HTTP library):

const express = require('express');
const axios = require('axios');
const app = express();

// Middleware para processar o body das requisições como JSON
app.use(express.json());

// Endpoint que recebe os webhooks
app.post('/webhook-receiver', (req, res) => {
  const event = req.body;

  // Processar o evento (aqui você adiciona a lógica que desejar)
  console.log('Webhook recebido:', event);

  // Retornar um status de sucesso para o serviço que enviou o webhook
  res.status(200).send('Evento processado com sucesso');
});

// Simulando o envio de um webhook para o Webhook.site
const webhookURL = 'https://webhook.site/unique-url';  // Substitua pela sua URL do Webhook.site

const sendWebhook = async () => {
  try {
    const payload = {
      event: 'payment_completed',
      data: {
        orderId: '12345',
        amount: 100.0,
        currency: 'USD'
      }
    };

    const response = await axios.post(webhookURL, payload);
    console.log('Webhook enviado com sucesso:', response.status);
  } catch (error) {
    console.error('Erro ao enviar webhook:', error);
  }
};

app.listen(3000, () => {
  console.log('Servidor rodando na porta 3000');

  // Enviar o webhook após o servidor iniciar
  sendWebhook();
});

In this example:

• We created a /webhook-receiver endpoint that simulates receiving a webhook.
• We use axios to simulate sending a webhook to Webhook.site, passing a payload with data from a fictitious payment.
• Webhook.site receives the notification and displays the request content on the panel.

Good Security Practices in Webhooks

Because webhooks involve sending data directly to a URL, it is essential to take some security precautions:

1. Origin Validation: Check whether the request is actually coming from the expected service. Many services offer a cryptographic signature (for example, using HMAC) that you can use to validate the authenticity of the request.

2. Use HTTPS: Always configure your webhook endpoints to use HTTPS, ensuring that communications between the service and your application are encrypted.

3. Authentication: In addition to HTTPS, some applications require webhook requests to include an authentication token or key as an extra layer of security.

4. Rate Limiting: Implement limits on the number of requests your server can process in a given period, preventing your application from being overloaded with too many requests in a short space of time.

Webhooks vs. APIs

People often confuse webhooks with APIs. Here's the main difference:

• APIs: They are active. Your application makes a request to a server and receives data in response. You need to "search" for the information.
• Webhooks: They are passive. The server automatically sends information to your application when an event occurs. You "receive" the information without having to ask.

Webhooks are especially useful in scenarios where you need real-time notifications, such as in payment systems, event notifications and integrations between different services.

Conclusion

Webhooks are a simple and efficient way to allow different systems to communicate automatically in real time. Using tools like Webhook.site, you can test and debug your webhooks before integrating them into production. Additionally, following good security practices ensures that your endpoints are protected from unwanted access.

If you are developing a modern application and need to integrate different services, webhooks are an excellent solution to automate communication between them.

If you have any questions or interesting experiences with webhooks, share them in the comments!