EasyRoutes API - Webhooks Guide

EasyRoutes webhooks support allows you to receive events programmatically in response to changes in your routes. 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:

• API access enabled (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 that interfaces directly with our Webhooks API instead. Check out some common Zapier Integrations.

1. Register a webhook endpoint

Go to EasyRoutes Settings > API and click Register webhook.

Configure:

• URL: Your HTTPS endpoint (e.g., https://yourserver.com/webhooks/easyroutes    )
• API version: Determines the payload format
• Topics: Which events to receive (see Webhook topics below)

Creating your first webhook generates a Webhook secret — you'll use this to verify requests are from EasyRoutes. See Verifying webhook requests for details on how to secure your endpoint.

2. Build a webhook handler

To receive webhooks, you need to:

• Accept POST     webhook requests on an HTTPS endpoint or server
  • Relevant webhook metadata like the topic and affected object ID are sent via headers as well as in the JSON body of the request.
  • The affected object itself (i.e. a Route     or RouteStop     ) is sent in the payload     field of the body.
  • See Webhook event overview below for details on the request format.
• Return a successful status code (2xx     ) to acknowledge the webhook quickly (within 10 seconds).
  • Avoid doing any complex logic that could cause a timeout synchronously in your endpoint handler.
• (Recommended) Verify the HMAC signature — see below.

Webhook event overview

All EasyRoutes webhook requests share a set of common fields, regardless of API version. These fields are serialized in a JSON payload in the body of the POST     request.

Sample:

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

Additional some of the metadata fields are mirrored in HTTP headers for convenience.

• X-EasyRoutes-Event-Id     
• X-EasyRoutes-Topic     
• X-EasyRoutes-Event-Timestamp     
• X-EasyRoutes-Version     
• X-EasyRoutes-Shopify-Shop     
• X-EasyRoutes-Organization     
• X-EasyRoutes-Object-Id     

Verifying webhook requests

EasyRoutes webhooks are signed using your unique Webhook secret     from Settings. The HMAC SHA256 hash is sent in the webhook request via the X-EasyRoutes-Hmac-Sha256     header. To verify that requests are sent by EasyRoutes, compute your own signature from the request body and verify it against the header signature.

Note: your webhook secret is distinct from your API secret key and is always available on the Settings page.

Example webhook endpoint

Here is an example endpoint implement in Go:

package main

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

// Webhook secret key example.
// Not recommend 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)
}

4. Testing your webhook

Once you've built your webhook endpoint and registered it in EasyRoutes, you can send a test event (topic     = TEST     ) to verify everything is working as expected.

If your endpoint returns 2xx    , you're ready.

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 event 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're 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.