Webhooks Guide

EasyRoutes webhooks allow you to receive events programmatically in response to changes in your routes, stops, drivers, and imported stops. In combination with using the EasyRoutes API, webhook events allow you to build powerful automation triggered by deliveries, route updates, or other events.

What you'll need:

• An active EasyRoutes paid plan and API credentials (see Getting Started Guide)
• A server with an HTTPS endpoint that can receive POST requests
• Familiarity with HMAC signature verification (optional but recommended)

Common use cases

Prefer no-code? Set up Zaps based on route- and stop-level updates using our Route Updated & Stop Status Updated Zapier triggers, which interface directly with our Webhooks API. Check out some common Zapier Integrations.

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/webhooks/easyroutes",
    "topics": ["STOP_STATUS_UPDATED", "ROUTE_DISPATCHED"]
  }' \
  https://easyroutes.roundtrip.ai/api/2024-07/webhooks

{
  "eventId": "evt-fa75b82d-2411-4cf8-b15f-cf3d8c91e919",
  "topic": "STOP_STATUS_UPDATED",
  "eventTimestamp": "2024-08-23T16:12:26-04:00",
  "apiVersion": "V2024_07",
  "objectId": "rst-abc123",
  "payload": {
    "id": "rte-6ffc8a79-e556-4ca4-9246-33850da3cedc",
    "name": "Monday AM Route",
    "stops": [...]
  }
}

package main

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/base64"
  "encoding/json"
  "io"
  "log"
  "net/http"
)

// Webhook secret key example.
// Not recommended to hardcode!
const easyroutesSecret = "PjV...w=="

type Event struct {
  EventId        string `json:"eventId"`
  Topic          string `json:"topic"`
  EventTimestamp string `json:"eventTimestamp"`
  ApiVersion     string `json:"apiVersion"`
  ObjectId       string `json:"objectId,omitempty"`
  Payload        []byte `json:"payload,omitempty"`
}

func main() {
  http.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) {
    b, err := io.ReadAll(r.Body)
    if err != nil {
      log.Printf("error reading webhook body: %v", err)
      w.WriteHeader(http.StatusServiceUnavailable)
      return
    }

    sig := r.Header.Get("X-EasyRoutes-Hmac-Sha256")
    if len(sig) == 0 {
      log.Printf("missing signature header")
      w.WriteHeader(http.StatusBadRequest)
      return
    }

    d, err := base64.StdEncoding.DecodeString(easyroutesSecret)
    if err != nil {
      log.Fatalf("error decoding secret: %v", err)
    }

    enc := hmac.New(sha256.New, d)
    enc.Write(b)
    expected := enc.Sum(nil)
    actual, err := base64.StdEncoding.DecodeString(sig)
    if err != nil {
      log.Printf("error decoding signature: %v", err)
      w.WriteHeader(http.StatusBadRequest)
      return
    }

    if !hmac.Equal(expected, actual) {
      log.Printf(
        "signature mismatch, expected=%s, actual=%s",
        base64.StdEncoding.EncodeToString(expected),
        base64.StdEncoding.EncodeToString(actual),
      )
      w.WriteHeader(http.StatusBadRequest)
      return
    }

    parsed := &Event{}
    err = json.Unmarshal(b, parsed)
    if err != nil {
      log.Printf("error parsing webhook body: %v", err)
      w.WriteHeader(http.StatusBadRequest)
      return
    }

    switch parsed.Topic {
    case "ROUTE_CREATED":
      // process event here
    }

    w.WriteHeader(http.StatusOK)
  })

  http.ListenAndServe(":8080", nil)
}

Webhook topics

Guidelines and best practices

The following section outlines some guidelines and best practices to be aware of when designing your EasyRoutes webhook handler.

Respond in a timely manner

Your handler should respond to a webhook request with a 2xx response within 10 seconds. If you take longer than that to respond, EasyRoutes may consider the delivery a failure. Failed webhooks are retried up to 10 times with exponential back-off for up to ~5 hours but are eventually dropped. Webhook endpoints that consistently fail may be deactivated (see below).

To respond quickly, avoid doing any heavy processing synchronously or making expensive downstream network calls to storage or other services. Consider setting up a queue to process webhook events asynchronously after responding immediately.

Handle duplicate events

In rare cases, EasyRoutes may send the same webhook event multiple times, even if your server acknowledged the request with a 2xx response. These retries can happen due to timeouts, dropped network traffic, or transient unavailability.

To avoid duplicate work, your webhook handler can use the eventId / X-EasyRoutes-Event-Id header as a unique event identifier.

Handle delayed or out-of-order events

Just as above, events may arrive out of order or delayed due to retries or transient unavailability. Your webhook handler can use the eventTimestamp / X-EasyRoutes-Event-Timestamp header to produce an ordering of events for a given object (i.e. a route). Using this, you may choose to ignore "earlier" events if you've already processed "later" ones for a given object.

Prevent replay attacks

You can verify that webhooks were sent by EasyRoutes by validating that the SHA256 HMAC of the request body computed using your webhook secret key matches the X-EasyRoutes-Hmac-Sha256 header on the request. However, to prevent replay or man-in-the-middle attacks you may also consider not processing webhooks (just responding with 2xx) if the eventTimestamp in the body is too old. The body timestamp cannot be changed by an attacker without affecting the computed signature, which they could only recompute if your webhook secret key is compromised.

Deactivated webhooks

Webhook endpoints that consistently fail to acknowledge events (return 2xx response within 10 seconds) may be deemed inactive and be deactivated by our system. Deactivated webhooks are highlighted with a badge on the API settings page:

To reactivate a deactivated webhook, just edit and save the webhook endpoint. However, if it continues to fail, it may be deactivated again in the future.