Webhooks

Webhooks let you register a URL that we will notify when critical events occur. Webhooks can be used to receive customer-arrival events. Common use cases include:

  • Receiving customer-arrival events in place of using the ARRIVE SDK in your monitor app
  • Sending push notification alerts to your monitor app
  • Integrating arrival events within your point-of-sale infrastructure

Configuring Webhooks

You can configure a webhook under the Account > Webhooks section of the ARRIVE dashboard. There is a single webhook per account. Events from sandbox and production are sent to the same webhook. You can test and inspect webhook events using an endpoint from RequestBin.

Receiving a Webhook Event

To receive webhook events, you must create an endpoint served from an HTTPS server. The endpoint must acknowledge the event by returning an HTTP 2xx status code within two seconds.

It is recommended that you immediately acknowledge the reception of the event and then process any IO or heavy computation asynchronously. Events will be retried up to two times with a one-minute delay between each retry.

When a trip is approaching or arrived, new events with the latest data for the trip will be sent frequently. If you want to know whether a trip has newly transitioned to the approaching or arrived state, check whether the data.estimates[].ack.token contains a new value for the trip.

The same event can be sent more than once. You can guard against duplicated events by making your endpoint processing idempotent.

Webhook events will be sent from one of three IP addresses:

  • 52.37.123.229
  • 52.37.246.23
  • 52.37.75.38

It is recommended that you whitelist these IP addresses to guarantee that the traffic your endpoint receives is legitimate.

Sample event:

{
  "event": "ad-estimates",
  "data": {
    "app_id": "com.curbside.hello",
    "estimates": [
      {
        "customer": {
          "email": "john.smith@example.com",
          "sms_number": "8883308304",
          "name": "John Smith",
          "vehicle": {
            "license_number": "2114705",
            "make": "Tesla",
            "model": "Model S"
          }
        },
        "eta": 120,
        "distance": 29.029977710719,
        "lat": 37.4259354,
        "lng": -122.1382713,
        "received_at": "2017-09-14T21:55:34Z",
        "site_csin": "hellocurbside_9388",
        "status": "arrived",
        "tid": "hello12345",
        "track_tokens": [
          {
            "dest_id": "25f8f222-6b6a-400e-bcf6-94790cc95daf",
            "track_token": "my_track_token",
            "pickup_window": {
               "start": "2017-09-14T20:00:00.000Z",
               "end": "2017-09-14T23:00:00.000Z"
             }
          }
        ],
        "ack": {
          "token": "df37a534-2a1b-4dd5-8709-c3b2a2a3df14"
        },
        "arrived": {
          "zone_name": "curbside"
        }
      }
    ],
    "production": false
  },
  "timestamp": "2017-09-14T21:55:53.802Z",
  "version": "2017-05-31"
}

Attribute Descriptions

Attribute Description
event Event name. Always ad-estimates .
data.app_id App ID that originated the event.
data.estimates List of open trips with arrival estimates. Empty if there are no open trips.
data.estimates[].customer.email Customer email, if provided, when starting the trip.
data.estimates[].customer.sms_number Customer mobile phone number, if provided, when starting the trip.
data.estimates[].customer.name Customer name, if provided, when starting the trip.
data.estimates[].customer.vehicle.license_number Customer vehicle license plate number, if provided, when starting the trip.
data.estimates[].customer.vehicle.model Customer vehicle model, if provided, when starting the trip.
data.estimates[].customer.vehicle.make Customer vehicle make, if provided, when starting the trip.
data.estimates[].eta ETA, in seconds, until the customer arrives at the site.
data.estimates[].distance Distance, in meters, from the site location.
data.estimates[].lat Last known latitude of the customer.
data.estimates[].lng Last known longitude of the customer.
data.estimates[].received_at ISO 8601 timestamp when ARRIVE server received the location update from the customer.
data.estimates[].site_csin Site ID for the arrival event.
data.estimates[].status Current status of the customer, which can be in-transit , approaching , or arrived .
data.estimates[].tid Customer Tracking Identifier (trackingIdentifier in the SDKs).
data.estimates[].track_tokens List of track tokens associated with this estimate.
data.estimates[].track tokens[].dest id Unique Curbside identifier for this trip.
data.estimates[].track tokens[].track token The track token for this trip, as set by your mobile app.
data.estimates[].track tokens[].pickup window.start Pickup time or start time of the pickup window, if provided, when starting the trip. Time is in UTC.
data.estimates[].track tokens[].pickup window.end End time of the pickup window, if provided, when starting the trip. Time is in UTC.
data.estimates[].ack.token A unique token generated for the trip when it first transitions to the approaching or arrived state. You can determine whether a trip has newly transitioned to approaching or arrived by checking whether this token has been seen before.
data.estimates[].arrived.zone_name Name of the zone.
data.production true if the event is from a production usage token.
timestamp ISO 8601 timestamp when the event was generated. This can be different from the current time if there is a retry.
version Event version string.