Webhooks API

The Webhooks API allows you to configure endpoints which will receive PUSH events from AutoGrab.

This API requires authentication and appropriate license attached to it.

Webhook Events

There are several types of events that you can listen to using the Webhooks API. The names and descriptions of each of these events are included below.

You can find example payloads for each of these events at the bottom of this page.

Name	Definition
ping	If you use the POST /v2/webhooks/{WEBHOOK_ID}/ping endpoint, your webhook will be called with the ping event to test the connection.
recapture_new	One of your Recapture customers was spotted on a used car listing website.
recapture_price_change	The listing price on one of your active Recapture customers changed.
recapture_delist	One of your Recapture customers removed their vehicle listing - either to cancel the sale or because it has been sold.
valuation_change	One of your previous price predictions has changed by (at least) the threshold defined in your valuation changes config (/valuations/changes)

Currently, only the ping, recapture_new and price_change events are in use. You can still configure your webhooks to listen to the other events in order to enable these events once they are supported.

If you need immediate access to Recapture price change and delist events for your use-case, please reach out to us at info@autograb.com.au

Create a new Webhook

To set up a webhook event subscriber, you'll first need to create the webhook using the AutoGrab API.

You must provide a few options in the request body:

• name: A name for the webhook. This is used for reference only.
• region: The region that you want to subscribe to events in (au or nz)
• format: The format that you want the PUSH events to be sent in (Currently, only json is supported)
• endpoint: The HTTP endpoint that you want the webhook to push to. You can include URL parameters in this to facilitate token-based auth.

Example

To perform an example request:

curl -XPOST -H 'ApiKey: {API_KEY}' \
    -H "Content-type: application/json" \
    -d '{
        "region": "au",
        "name": "Sandbox Webhook",
        "format": "json",
        "endpoint": "https://sandbox.webhook.new"
    }' 'https://api.autograb.com.au/v2/webhooks'

An example response payload is:

{
    "success": true,
    "webhook": {
        "id": "a9fb47f6-3d1d-4945-9f4d-f45b12a63797",
        "created_at": "2022-07-15T03:53:59.872Z",
        "name": "Sandbox Webhook",
        "format": "json",
        "events": ["recapture_new"],
        "endpoint": "https://example.com/push"
    }
}

You can explore this request further in the API Playground.

Get a list of your webhooks

A GET request to /v2/webhooks?region={REGION} will return a list of all your configured webhooks in the given region.

Example

To perform an example request:

curl "https://api.autograb.com.au/v2/webhooks?region=au" \
     -H 'ApiKey: {API_KEY}'

An example response payload is:

{
  "success": true,
  "webhooks": [
    {
      "id": "9a275d4f-5476-4d86-b691-f0f37d985909",
      "created_at": "2022-07-15T03:54:07.431Z",
      "name": "Sandbox Webhook",
      "format": "json",
      "events": ["recapture_new", "recapture_delist"],
      "endpoint": "https://sandbox.example.com/push"
    },
    {
      "id": "a9fb47f6-3d1d-4945-9f4d-f45b12a63797",
      "created_at": "2022-07-15T03:53:59.872Z",
      "name": "Production Webhook",
      "format": "json",
      "events": ["recapture_new"],
      "endpoint": "https://example.com/push"
    }
  ]
}

You can explore this request further in the API Playground.

Get the configuration of a single webhook

A GET request to /v2/webhooks/{WEBHOOK_ID}?region={REGION} will return the configuration of the webhook with the corresponding ID.

The payloads are the same as the /v2/webhooks route but only a single webhook is returned instead of an array.

If you try to access a webhook in a different region to the one specified in the request, you will receive an Invalid Region error. Additionally, accessing a webhook that your account does not have permission to view will return a You don't have permission to access that webhook error.

If you attempt to view a webhook that doesn't exist, you will receive an Invalid Webhook ID error.

Example

To perform an example request:

curl "https://api.autograb.com.au/v2/webhooks/{WEBHOOK_ID}?region=au" \
     -H 'ApiKey: {API_KEY}'

An example response payload is:

{
    "success": true,
    "webhook": {
        "id": "a9fb47f6-3d1d-4945-9f4d-f45b12a63797",
        "created_at": "2022-07-15T03:53:59.872Z",
        "name": "Sandbox Webhook",
        "format": "json",
        "events": ["recapture_price_change"],
        "endpoint": "https://example.com/push"
    }
}

You can explore this request further in the API Playground.

Modify the configuration of a single webhook

A PATCH request to /v2/webhooks/{WEBHOOK_ID}?region={REGION} allows you to modify any of the properties of the corresponding Webhook.

Only the fields specified in the request body will be modified, and passing a blank ("") value will remove the property from the webhook where applicable.

The response includes the updated webhook, as well as a map of every property that changed.

The same errors as the above (GET /v2/webhooks/${WEBHOOK_ID}) request apply, and a Request validation failed error may also be thrown if you provide any invalid Webhook Event names. Refer to the top of this page for a list of Webhook Events and their descriptions.

Example

To perform an example request:

curl -XPATCH -H 'ApiKey: {API_KEY}' \
    -H "Content-type: application/json" -d '{
        "name": "Updated Sandbox Webhook",
        "endpoint": "https://sandbox.example.com/push",
        "events": ["recapture_new"]
    }' 'https://api.autograb.com.au/v2/webhooks/{WEBHOOK_ID}?region=au'

An example response payload is:

{
    "success": true,
    "webhook": {
        "id": "a9fb47f6-3d1d-4945-9f4d-f45b12a63797",
        "created_at": "2022-07-15T03:53:59.872Z",
        "name": "Updated Sandbox Webhook",
        "format": "json",
        "events": ["recapture_new"],
        "endpoint": "https://example.com/push"
    },
    "updates": {
        "name": "Updated Sandbox Webhook",
        "endpoint": "https://sandbox.example.com/push",
        "events": ["recapture_new"]
    }
}

You can explore this request further in the API Playground.

Delete a webhook

A DELETE request to /v2/webhooks/{WEBHOOK_ID}?region={REGION} will permenantly delete the webhook.

The response payload includes the configuration of the deleted webhook, as seen in the examples below.

You may receive a small number of additional messages on your webhook's endpoint after deleting the webhook due to queued messages being sent through, but no new messages will be sent to your webhook after it has been deleted, and there is no way to recover the webhook without re-creating it.

Example

To perform an example request:

curl -XDELETE "https://api.autograb.com.au/v2/webhooks/{WEBHOOK_ID}?region=au" \
     -H 'ApiKey: {API_KEY}'

An example response payload is:

{
    "success": true,
    "webhook": {
        "id": "a9fb47f6-3d1d-4945-9f4d-f45b12a63797",
        "created_at": "2022-07-15T03:53:59.872Z",
        "name": "Sandbox Webhook",
        "format": "json",
        "events": ["recapture_price_change"],
        "endpoint": "https://example.com/push"
    }
}

You can explore this request further in the API Playground.

Ping a webhook

A POST request to /v2/webhooks/{WEBHOOK_ID}/ping?region={REGION} will send a ping event to your webhook with an example payload.

You can't explicitly subscribe to ping events, as it is a special event type that is only sent when requested using this endpoint.

Example

To perform an example request:

curl -XPOST "https://api.autograb.com.au/v2/webhooks/{WEBHOOK_ID}/ping?region=au" \
     -H 'ApiKey: {API_KEY}'

An example response payload is:

{
    "success": true,
    "ping": {
        "webhook_id": "a9fb47f6-3d1d-4945-9f4d-f45b12a63797",
        "at": "2022-07-15T03:53:59.872Z",
        "format": "json",
        "endpoint": "https://example.com/push",
        "response_time_ms": 83,
        "response_status": 200
    }
}

You can explore this request further in the API Playground.

Webhook Payloads

Example payloads for the webhook events that are currently in use are included below.

ping

{
    // The Webhook Event type (required)
    "event": "ping",
    // The webhook event payload (required)
    "data": {
        "webhook_id": "a9fb47f6-3d1d-4945-9f4d-f45b12a63797",
        "at": "2022-09-03T00:37:57.095Z"
    }
}

recapture_new

{
    // The Webhook Event type (required)
    "event": "recapture_new",
    // The Webhook Event payload (required)
    "data": {
        // The Recapture record which has been seen online
        "customer": {
            // The internal ID of the Recapture client (required)
            "id": "05df2f33-1d03-404c-b0c2-dfbecaa65fff", // Required
            // The ISO timestamp when the event took place (required)
            "last_updated": "2022-09-03T00:37:57.095Z",
            // The registration plate that you were tracking (nullable)
            "rego": "BMT038",
            // The registration state that you uploaded alongside the customer record, if applicable (nullable)
            "state": "VIC",
            // The VIN uploaded for the Recapture customer (nullable)
            "vin": null,
            // The name uploaded for the Recapture Customer (nullable)
            "client_name": "Raph",
            // The mobiule number uploaded for the Recapture Customer (nullable)
            "mobile_number": "+61 123 456 789",
            // The ISO formatted sale date uploaded alongside the customer record, if applicable (nullable)
            "sale_date": "2022-03-02T00:00:00.000Z",
            // The ISO formatted expiry date for the Recapture customer record, if applicable (nullable)
            "expiry_date": "2022-11-20T00:00:00.000Z",
            // The vehicle title, determined by a registration or listing lookup (nullable)
            "vehicle_title": "2019 Volkswagen Polo 85TSI Comfortline",
            // Any additional data that was uploaded alongside the customer record (required)
            "additional_fields": {
                "notes": "Three free services included in package"
            },
            // An array including details for each time one of the customer's vehicles was spotted online (required)
            "sightings": [
                {
                    // The date when the vehicle was spotted online (required)
                    "at": "2022-09-03T00:37:57.095Z", 
                    // The AutoGrab Lead ID that includes the listing where the vehicle was spotted online (required)
                    "lead_id": "au_volkswagen_bmt038",
                    // The URL where the vehicle was listed online (required)
                    "listing_url": "https://www.carsales.com.au/cars/details/2019-volkswagen-polo-85tsi-comfortline-aw-auto-my19/OAG-AD-20356677",
                    // The title of the listing (required)
                    "listing_title": "2019 Volkswagen Polo 85TSI Comfortline AW Auto MY19",
                    // The price that the vehicle was listed for at the time of capture (nullable)
                    "listing_price": 26890,
                }
            ]
        }
    }
}

valuation_change

{
    // The Webhook Event type (required)
    "event": "valuation_change",
    // The webhook event payload (required)
    "data": {
        // The pricing record which has changed in value
        "pricing_record": {
            // The unique Pricing Record ID (required)
            "id": "a9fb47f6-3d1d-4945-9f4d-f45b12a63797",
            // The AutoGrab Vehicle ID associated with the pricing record (required)
            "vehicle_id": "5478860653068288",
            // The ISO timestamp when the pricing record was first created (required)
            "created_at": "2022-08-20T07:20:32.412Z",
            // The registration plate associated with the pricing record (nullable)
            "rego": "ZXX678",
            // The registration state associated with the pricing record, if applicable (nullable)
            "state": "VIC",
            // The VIN associated with the pricing record (nullable)
            "vin": null,
            // The odometer input for the pricing record (required)
            "kms": 32000,
            // The current price prediction for the given vehicle at the kilometers entered (required)
            "price": 36782,
            // The current predicted retail price (required)
            "retail_price": 36782,
            // The current predicted trade price (required)
            "trade_price": 32100,
            // The adjustments and overrides that are currently applied to the pricing record (nullable)
            // Matches the adjustment schema from the `/v2/valuations/predict` endpoint
            "adjustment": null,
            // An array of all the recorded valuation changes that this pricing record has had (required)
            "changes": [
                {
                    // The unique change ID (required)
                    "id": "ba4b3912-ae25-44c1-8a66-36ca68fac859",
                    // The change type (valuation or configuration) (required)
                    // A valuation change implies that the market has shifted, 
                    // whereas a configuration change is simply a result of your 
                    // adjustments/overrides configuration changing
                    "type": "valuation",
                    // The ISO timestamp when the change occurred (required)
                    "at": "2022-09-03T01:03:55.382Z",
                    // The new price (required)
                    "new_price": 36782,
                    // The new retail price (required)
                    "new_retail_price": 36782,
                    // The new trade price (required)
                    "new_trade_price": 32100,
                    // The old price (required)
                    "old_price": 38520,
                    // The old retail price (required)
                    "old_retail_price": 38520,
                    // The old trade price (required)
                    "old_trade_price": 34200
                },
                {
                    // Any previous changes to the pricing record will also be
                    // included here, following the same schema as above
                    "id": "46610b56-f3c7-4744-8adf-021c0aba1cc4",
                    "type": "configuration",
                    "at": "2022-09-01T03:12:32.524Z",
                    "new_price": 38520,
                    "new_retail_price": 38520,
                    "new_trade_price": 34200,
                    "old_price": 38520,
                    "old_retail_price": 37520,
                    "old_trade_price": 33900 
                }
            ]
        },
        // This is a copy of the specific valuation change that caused the webhook to trigger (required)
        // in case many changes occur in a short timespan, this is the source of truth for the
        // exact change that triggered the event.
        "change": {
            "id": "ba4b3912-ae25-44c1-8a66-36ca68fac859",
            "type": "valuation",
            "at": "2022-09-03T01:03:55.382Z",
            "new_price": 36782,
            "new_retail_price": 36782,
            "new_trade_price": 32100,
            "old_price": 38520,
            "old_retail_price": 38520,
            "old_trade_price": 34200
        }
    }
}