Webhooks

Creating a New Callback

Webhooks are configured directly on the PAVE Dashboard. For separate guidance on how to configure a webhook on the dashboard, please also read here

Endpoint:

https://openapi.paveapi.com/v1/callbacks

Introduction

This endpoint allows you to set up a new callback for your API-Key.

Headers

The following headers must be included in the request:

API-Key: A string that represents the API-Key provided for your account.
API-Token: A string that represents the API-Token used when the session was created.
API-Timestamp: A UTC datetime string in the format of "2021-05-30T12:49:19Z".

Body Parameters

The following parameters must be included in the request body:

event: A string that represents one of the supported events. The options are:
1. SESSION:SMS_PROCESS
2. SESSION:STAGE_CHANGE
3. SESSION:STATUS_CHANGE
4. SESSION:COMPLETE
url: A string that represents the endpoint URL for your callback to receive the events.

The following parameters are optional:

method: A string that represents the method to be used. POST is the default if not provided.
headers: A string that represents the authentication headers to be included (API key, token).
payload: A string that represents the attributes to be sent along with the default payload for the supported events.

Supported Events

SESSION:SMS_PROCESS

Triggered when the process changes for the SMS Message

SESSION:STAGE_CHANGE

Triggered when User captures each photo in the process

SESSION:STATUS_CHANGE

Triggered when the session status changes

SESSION:COMPLETE

Triggered when the session is completed

SESSION:NOTE_INSERT

Triggered when a note has been inserted to the session

API Endpoints

Retrieve a list of all callbacks: GET https://openapi.paveapi.com/v1/callbacks
Retrieve a specific callback by event: GET https://openapi.paveapi.com/v1/callbacks/:event
Create a new callback: POST https://openapi.paveapi.com/v1/callbacks
Update an existing callback: PUT https://openapi.paveapi.com/v1/callbacks/:event
Delete a callback: DELETE https://openapi.paveapi.com/v1/callbacks/:event"

Sample Response (200: OK)

{
    "api_key": "<your_request_api_key",
    "event": "SESSION:STAGE_CHANGE",
    "url": "https://your_sms_callback_url",
    "method": "POST",
    "headers": {
        "Authorization": "Bearer <jwt_token>"
    },
    "payload": {
        "source": "PAVE", // additional attributes to pass along; setting on create callback
    }
}

Sample Response (400: Bad Request)

{
    "message": "Missing required fields."
}

Supported Callback Events

Webhook for Event "SESSION:SMS_PROCESS"

When we receive the result of an SMS message from the message provider, we will send it to the callback URL along with the following default payload.

Payload:

The payload for this webhook will include the following fields:

session_key: A string that represents the key of the session associated with the SMS message.
event: A string that represents the event that triggered the webhook. The value for this field will always be "SESSION:SMS_PROCESS".
name: A string that represents the name of the recipient of the SMS message. This field is optional.
phone: A string that represents the phone number associated with the session's SMS message.
status: A string that represents the status of the SMS message. The value for this field will be either "success" or "error".
message: A string that represents an error message if the status is "error".
timestamp: A string in ISO8601 format that represents the date and time when the SMS result was received.

Example:

{
    "session_key": "SWP-7LQUT*9BHE",
    "event": "SESSION:SMS_PROCESS",
    "name": "John Doe",
    "phone": "555-555-5555",
    "status": "success",
    "message": "",
    "timestamp": "2021-05-29T03:45:27+05:00"
}

PAVE's webhook for the event "SESSION:SMS_PROCESS" is used to notify interested parties when the result of an SMS message is received. The payload of this webhook includes information about the session, the recipient, the status of the SMS message, and the timestamp of when the result was received. This information can be used to update other systems or take other actions in response to the receipt of an SMS result.

Webhook for Event "SESSION:STAGE_CHANGE"

When a captured photo has been processed, we will send the status, as well as the timestamp, to the callback URL along with the following default payload.

Payload:

The payload for this webhook will include the following fields:

session_key: A string that represents the key of the session associated with the processed photo.
event: A string that represents the event that triggered the webhook. The value for this field will always be "SESSION:STAGE_CHANGE".
photo_code: An integer that represents a unique identifier for the photo.
photo_label: A string that represents the label given to the photo, such as "Interior".
photo_url: A string that represents the URL where the captured photo can be found.
photo_status: A string that represents the status of the photo. The value for this field will be either "accepted" or "rejected".
message: A string that represents an error message if the status is "rejected".
timestamp: A string in ISO8601 format that represents the date and time when the photo was processed.

Example:

{
    "session_key": "SWP-7LQUT*9BHE",
    "event": "SESSION:STAGE_CHANGE",
    "photo_code": 2,
    "photo_label": "Interior",
    "photo_url": "https://capturedphotourl.com",
    "photo_status": "accepted",
    "message": "",
    "timestamp": "2021-05-29T03:45:27+05:00"
}

PAVE's webhook for the event "SESSION:STAGE_CHANGE" is used to notify interested parties when a captured photo has been processed. The payload of this webhook includes information about the session, the processed photo, and the status of the photo, as well as the timestamp of when the photo was processed. This information can be used to update other systems or take other actions in response to the processing of a photo.

Webhook for Event "SESSION:STATUS_CHANGE"

When the status of a session changes from STARTED to PROCESS, PROCESS to QC_PASSED, or QC_PASSED to CONFIRM, we will send the new status, as well as the timestamp, to the callback URL along with the following default payload.

Payload:

The payload for this webhook will include the following fields:

session_key: A string that represents the key of the session whose status has changed.
event: A string that represents the event that triggered the webhook. The value for this field will always be "SESSION:STATUS_CHANGE".
status: A string that represents the new status of the session. The value for this field will be one of the following: "STARTED", "PROCESS", QC_PASSED, or "CONFIRM".
timestamp: A string in ISO8601 format that represents the date and time when the status change occurred.

Example:

{
    "session_key": "SWP-7LQUT*9BHE",
    "event": "SESSION:STATUS_CHANGE",
    "status": "STARTED",
    "timestamp": "2021-05-29T03:45:27+05:00"
}

PAVE's webhook for the event "SESSION:STATUS_CHANGE" is used to notify interested parties when the status of a session changes. The payload of this webhook includes information about the session, the new status of the session, and the timestamp of when the status change occurred. This information can be used to update other systems or take other actions in response to a change in session status.

STATUS

DEFINITION

STARTED

The user has started the inspection process but has not yet captured any vehicle images

PROCESS

The user has started capturing the vehicle images on the PAVE Web App

QC_PASSED

All vehicle images have been captured by the user and have been accepted by PAVE's Image QC engine

CONFIRM

The vehicle inspection is complete and the Condition Report is now being generated

COMPLETE

The Condition Report has been generated and the inspection is now complete

EXPIRED

The session has been idle for longer than the configured expiration window

Webhook for Event "SESSION:COMPLETE"

When the status of a session changes from CONFIRM to COMPLETE, we will send the results of the session to the callback URL. The payload will be exactly the same as the result of the API endpoint "GET Session Results".

Payload:

The payload for this webhook will include the same information as the result of the API endpoint "GET Session Results". The exact structure and fields of the payload will depend on the specific implementation of the API.

PAVE's webhook for the event "SESSION:COMPLETE" is used to notify interested parties when a session is complete and its results are available. The payload of this webhook includes the same information as the result of the API endpoint "GET Session Results", including the session key, status, timestamp, and results. This information can be used to update other systems or take other actions in response to the completion of a session.

PAVE Inspection Results Data

This link below provides a PDF document that includes a detailed description of the various objects used in an inspection session JSON that is SESSION:COMPLETE.

These objects include the Session Object, which contains information about the inspection session, such as the session key, theme, status, and contact details. The Vehicle Object has information on the inspected vehicle, including the VIN, make, model, and odometer reading. The Photos Object contains information about the photos taken during the inspection, including the URL where they are stored and whether they were approved in the photo QA process. The Location Object provides details about the location of the inspection. Lastly, the Inspection Object contains information about the damages detected during the inspection, including the total number of damages and their maximum grade per item.

Webhook for Event "SESSION:NOTE_INSERT"

This event is triggered when a new note is added to a session. The following section provides a description of the payload that will be sent with the webhook.

Payload:

The payload for this webhook will contain the following fields:

session_key: A string that represents the key of the session where the note was inserted.
event: A string that represents the event that triggered the webhook. For this event, the value will always be "SESSION:NOTE_INSERT".
timestamp: A string in ISO8601 format that represents the date and time when the note was inserted.
title: A string that represents the title of the inserted note.
description: A string that represents the description of the inserted note.
user: A string that represents the user who inserted the note. This could be the username of a logged-in user or the word "guest" if the note was inserted by a guest.

Example:

  {
  "session_key": "SWP-7LQUT*9BHE",
  "event": "SESSION:NOTE_INSERT",
  "timestamp": "2021-05-29T03:45:27+05:00",
  "title": "Note title",
  "description": "Note description",
  "user": "Logged-username"
}

PAVE's webhook for the event "SESSION:NOTE_INSERT" is used to notify interested parties when a new note is added to a session. The payload of this webhook contains information about the session, the note, and the user who inserted the note. This information can be utilized to update other systems or take other actions in response to the addition of a new note.

PreviousDELETE Session NextGET All Callbacks

Last updated 3 months ago