# Webhooks

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

This API requires [authentication](https://docs.autograb.com.au/guide/auth/) and appropriate license attached to it.

### Create a new Webhook <a href="#create-a-new-webhook" id="create-a-new-webhook"></a>

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

### Webhook Events <a href="#webhook-events" id="webhook-events"></a>

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.

<table><thead><tr><th width="257.40234375">Name</th><th>Definition</th></tr></thead><tbody><tr><td><code>ping</code></td><td>If you use the <code>POST /v2/webhooks/{WEBHOOK_ID}/ping</code> endpoint, your webhook will be called with the <code>ping</code> event to test the connection.</td></tr><tr><td><code>recapture_new</code></td><td>One of your Recapture customers was spotted on a used car listing website.</td></tr><tr><td><code>recapture_price_change</code></td><td>The listing price on one of your active Recapture customers changed.</td></tr><tr><td><code>recapture_delist</code></td><td>One of your Recapture customers removed their vehicle listing - either to cancel the sale or because it has been sold.</td></tr><tr><td><code>claim_report_generated</code></td><td>Notification for a PAV claim report being generated and contain the details of the specific report</td></tr></tbody></table>

### Testing a Webhook

To generate an example response to confirm the configuration of an endpoint add the `ping` subscription to your webhook even subscriptions and POST to the `/ping` route below.

### Delete a webhook <a href="#delete-a-webhook" id="delete-a-webhook"></a>

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.

### Get the configuration of a single webhook <a href="#get-the-configuration-of-a-single-webhook" id="get-the-configuration-of-a-single-webhook"></a>

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.

### Update the configuration of a single webhook <a href="#modify-the-configuration-of-a-single-webhook" id="modify-the-configuration-of-a-single-webhook"></a>

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.