# Accessing webhook subscriptions

## Registering a webhook for your account

To register a webhook for your account, make a POST request to the webhooks endpoint `https://api.goshippo.com/webhooks`.


```shell
curl --location --request POST 'https://api.goshippo.com/webhooks' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "<CLIENT_OWNED_URL>",
    "event": "<YOUR_EVENT>",
    "is_test": "true" //this value is defaulted to false and is optional
}'
```

The event field can take one of the following five values:

* `transaction_created`
* `transaction_updated`
* `track_updated`
* `batch_created`
* `batch_purchased`


Additionally, you can set the `event` to `all`. This acts as a catch-all for all supported events.

A successful call to the registration endpoint will return a JSON object.


```json
{
    "active": true,
    "event": "<YOUR_EVENT>",
    "object_created": "2021-06-28T15:44:11.647Z",
    "object_id": "<WEBHOOK_OBJECT_ID_GUID>",
    "object_updated": "2021-06-28T15:44:11.647Z",
    "object_owner": "<Account Owner Email>",
    "url": "<CLIENT_REGISTERED_URL>",
    "is_test": true
}
```

## Retrieving a single webhook

To retrieve a webhook, make a GET request to the webhooks endpoint with the object ID of your webhook `https://api.goshippo.com/webhooks/<WEBHOOK_OBJECT_ID_GUID>`.


```shell
curl --location --request GET 'https://api.goshippo.com/webhooks/<WEBHOOK_OBJECT_ID_GUID>' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json'
```

A successful call returns a JSON object similar to this.


```json
{
    "active": true,
    "event": "<YOUR_EVENT>",
    "object_created": "2021-06-28T15:44:11.647Z",
    "object_id": "<WEBHOOK_OBJECT_ID_GUID>",
    "object_updated": "2021-06-28T15:44:11.647Z",
    "object_owner": "<Account Owner Email>",
    "url": "<CLIENT_REGISTERED_URL>",
    "is_test": true
}
```

To get a paginated list of all webhooks associated with your account, make a GET request to `https://api.goshippo.com/webhooks` without an object ID.

## Retrieving all active webhooks

To retrieve a list of all webhooks associated with your account, make a GET request to the webhooks endpoint `https://api.goshippo.com/webhooks/`.


```shell
curl --location --request GET 'https://api.goshippo.com/webhooks/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json'
```

A successful call returns a JSON object similar to this.


```json
{
    {
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "active": true,
      "event": "track_updated",
      "object_created": "2023-01-26T17:37:56.848Z",
      "object_id": "9c9783fa0e1148c98eba040141801119",
      "object_updated": "2023-01-26T17:37:56.848Z",
      "object_owner": "<Account Owner Email>",
      "url": "<CLIENT_REGISTERED_URL>",
      "is_test": false
    },
    {
      "active": true,
      "event": "track_updated",
      "object_created": "2023-01-26T17:36:34.715Z",
      "object_id": "a346d9e481b14dcfb6df48c19bfeacca",
      "object_updated": "2023-01-26T17:36:34.715Z",
      "object_owner": "<Account Owner Email>",
      "url": "<CLIENT_REGISTERED_URL>",
      "is_test": true
    }
  ]
}
}
```

## Deleting a webhook subscription

To delete a webhook subscription, make a DELETE request to the webhook endpoint with the object ID of your webhook `https://api.goshippo.com/webhooks/<WEBHOOK_OBJECT_ID_GUID>`.


```shell
curl --location --request DELETE 'https://api.goshippo.com/webhooks/<WEBHOOK_OBJECT_ID_GUID>' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw ''
```

This returns no body but will return a successful **2XX** status.