How to Use Axios for Third-Party Webhooks

Webhooks allow applications to communicate in real time by sending automated HTTP POST requests when specific events occur. This guide explains how to use the Axios HTTP client to send and interact with third-party webhooks in a Node.js or JavaScript environment. You will learn how to configure POST requests, manage authentication, secure payloads with signatures, implement error handling, and set request timeouts.

1. Installing Axios

To get started, install Axios in your Node.js project using npm or yarn:

npm install axios

2. Sending a Basic Webhook Request

Most webhooks require sending a POST request containing a JSON payload to the third-party endpoint.

const axios = require('axios');

async function sendWebhook(url, data) {
  try {
    const response = await axios.post(url, data, {
      headers: {
        'Content-Type': 'application/json',
      },
      timeout: 5000, // 5 seconds timeout
    });

    console.log(`Webhook delivered successfully: Status ${response.status}`);
    return response.data;
  } catch (error) {
    if (error.response) {
      // The server responded with a status code outside the 2xx range
      console.error(`Webhook failed with status: ${error.response.status}`);
      console.error('Response data:', error.response.data);
    } else if (error.request) {
      // The request was made but no response was received
      console.error('No response received from webhook endpoint:', error.message);
    } else {
      // Something happened in setting up the request
      console.error('Error configuring webhook request:', error.message);
    }
    throw error;
  }
}

// Example usage
const webhookUrl = 'https://api.example.com/webhooks/incoming';
const eventPayload = {
  event: 'order.created',
  timestamp: new Date().toISOString(),
  data: {
    orderId: 'ORD-12345',
    amount: 99.99,
    currency: 'USD'
  }
};

sendWebhook(webhookUrl, eventPayload);

3. Adding Authentication and Custom Headers

Third-party providers often require authentication tokens, API keys, or custom identification headers.

const axios = require('axios');

async function sendAuthenticatedWebhook(url, payload, authToken) {
  const config = {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${authToken}`,
      'X-App-Client-ID': 'your-client-id',
      'User-Agent': 'YourApp-WebhookService/1.0'
    }
  };

  return await axios.post(url, payload, config);
}

4. Securing Webhooks with HMAC Signatures

Many webhook systems (e.g., GitHub, Stripe, Shopify) require an HMAC SHA-256 signature in the request headers so the receiver can verify that the payload was not tampered with.

const axios = require('axios');
const crypto = require('crypto');

async function sendSignedWebhook(url, payload, secret) {
  const payloadString = JSON.stringify(payload);
  
  // Generate the HMAC signature
  const signature = crypto
    .createHmac('sha256', secret)
    .update(payloadString)
    .digest('hex');

  const config = {
    headers: {
      'Content-Type': 'application/json',
      'X-Hub-Signature-256': `sha256=${signature}`
    }
  };

  return await axios.post(url, payloadString, config);
}

5. Best Practices for Webhook Requests