Arrive Webhooks

Summary

Webhooks enables partners to receive notifications via an API whenever a booking has been created or cancelled in the Arrive system.

Arrive partners interested in using webhooks should contact our support team (partner-support@arrive.com).

Version Changes

  • v1.0: No changes in this version
  • v1.1: Adding support for partner booking creation

Event Types

There are two event types that are supported by our webhook framework:

  • Create Partner Booking
  • Cancel Partner Booking

Partner Requirements

In order to use this webhook system, the partner must create an API endpoint for each of the event types for which they wish to receive notifications.

For greater flexibility, we have made these endpoints highly configurable. Below are the required configuration details.

Authorization Headers

The partner must define some sort of authorization in the headers (must be static authorization, no JWT). Examples include:

  • Authorization: Bearer AbCdEf123456
  • X-Access-Token: AbCdEf123456
  • parkwhiz-auth: AbCdEf123456

The same authorization pattern should apply to each of the endpoints the partner creates.

Endpoints

The partner can choose to receive notifications for one or more of the event types defined above. The partner needs to make an endpoint for each event type.

Note: All endpoints must be POST endpoints.

Create Partner Booking Endpoint

The partner may configure create_booking_endpoint to an endpoint that they choose. Examples include:

  • POST /bookings
  • POST /create_booking
  • POST /arrive/bookings/create

Cancel Partner Booking Endpoint

The partner may configure cancel_booking_endpoint to an endpoint that they choose. Examples include:

  • POST /cancellations
  • POST /cancel_booking
  • POST /arrive/bookings/cancel

Request

When a user creates or cancels a booking that is attributed to your partner, we will hit the corresponding POST endpoint defined above with the following POST body.

The id represents the Arrive booking ID.

{ id: 100094328 }

Responses

The partner must set up each endpoint to return the below response codes. Note that if the partner endpoint returns 404, Arrive will retry the request until we receive a successful response.

Status Situation Will Retry?
202 Partner successfully accepted callback No
400 Duplicate callback request, already accepted into system No
401 Unauthorized callback request No
404 Partner could not accept callback Yes

Implementing the 400 response code is completely optional. If the partner does not choose to implement this response code, the endpoint should return 202 for the same behavior.

If the partner does implement the 400 response code, the endpoint must also return the following JSON body when the 400 is sent: {"code": "duplicate_request"}

Activate the Webhook

To activate the webhook, please contact Arrive with the following fields:

Field Example
auth_header_key Authorization
auth_header_value Bearer AbCdEf123456
base_api_url https://webhooks.partner.com
create_booking_endpoint* /arrive/bookings
cancel_booking_endpoint* /arrive/bookings/cancel

*The partner should only supply a field if they want to receive API events for that event type. For example, if the partner only wants to receive notifications for cancellation events, they would only supply the cancel_booking_endpoint field.

Additional Data

When a partner receives an API notification, they can use the provided booking id to retrieve any additional data they might need about that booking (i.e. user info, location info, booking info).

All of this additional booking data can be retrieved by calling our GET /bookings/:id (view documentation) endpoint with the booking id provided in the callback.

The partner must use a partner scoped OAuth Bearer Token to call this endpoint.

Last updated June 5, 2020