Webhooks

Kourier's webhooks allow you to receive real-time updates about deliveries and other events. You can set up webhooks to automatically get notified when specific events happen, such as a delivery status change.

Setting Up Webhooks

To start using webhooks, you'll need to configure a webhook URL in your Kourier dashboard. Kourier will send an HTTP POST request to this URL whenever an event occurs.

Webhook Configuration

1. Navigate to the Webhooks section in the Kourier dashboard.
2. Enter your Webhook URL (this should be an endpoint on your server that can handle POST requests).
3. Select the events you want to subscribe to.
4. Click Save to activate your webhook.

Webhook Events

Kourier supports the following events:

• delivery.created: Triggered when a new delivery is created.
• delivery.updated: Triggered when a delivery's status is updated (e.g., in_transit, delivered).
• delivery.cancelled: Triggered when a delivery is canceled.

Webhook Payload

Each webhook event sends a JSON payload to your endpoint with details about the event. Below is an example payload for a delivery status update.

Example Payload

{
  "event": "delivery.updated",
  "delivery_id": "abc123",
  "status": "in_transit",
  "timestamp": "2024-09-14T14:30:00Z"
}

Handling Webhooks

Your server should be prepared to handle incoming POST requests from Kourier's webhook service. Here's an example of how to handle a webhook event in Node.js:

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

app.use(express.json());

app.post('/webhook', (req, res) => {
  const event = req.body;

  // Handle the event
  switch (event.event) {
    case 'delivery.updated':
      console.log(`Delivery ${event.delivery_id} is now ${event.status}`);
      break;
    case 'delivery.cancelled':
      console.log(`Delivery ${event.delivery_id} was cancelled`);
      break;
    default:
      console.log(`Unhandled event: ${event.event}`);
  }

  // Return a 200 response to acknowledge receipt of the event
  res.sendStatus(200);
});

app.listen(3000, () => console.log('Webhook server is running on port 3000'));

Security

To ensure that the webhooks you receive are from Kourier, you should verify the request's authenticity by checking the Authorization header. Kourier includes a unique token in the header for each webhook request.

Example Header

Authorization: Bearer WEBHOOK_SECRET_TOKEN

Compare the WEBHOOK_SECRET_TOKEN with the token you configured in your Kourier dashboard to verify the request's authenticity.

Response Codes

When your server receives a webhook, it should return a 2xx HTTP status code to acknowledge the receipt. If a 2xx response is not received, Kourier will retry the webhook a few times.

• 2xx: Success
• 4xx: Client error (e.g., invalid endpoint)
• 5xx: Server error (e.g., webhook handler not functioning)

---

Example Webhook Error Response

If your webhook handler encounters an error, you can return a status code along with an error message. Example:

{
  "error": "Invalid request data",
  "details": "Missing delivery_id"
}

Make sure to handle webhooks efficiently to prevent retries and delays in processing real-time delivery updates.