Setting up and Managing Webhooks

This section provides request and response examples for the various operations that are available for webhooks with the service.

Setting up a webhook is a great way to make sure you're able to retrieve the latest updates without worrying about issuing continuous API requests to check the status of your card updates.

When we get a card update associated with one of your subscriptions you'll get a notification to your webhook URL with the details.

Creating a Webhook

The end-point you would use for this function is:

/api/v4/accounts/{accountId}/webhooks

The HTTP method would be POST.

The request body would be a JSON object containing the parameters url and event.

Where the url property is the URL you would like to receive your webhook notifications and the event property is the type of event that you would like to issue webhooks to your webhook.

For an Account Updater API webhook to work the only valid value for the event parameter is ACCOUNT_UPDATER_BATCH_UPDATES.

Example Request Body:

{
  "url": "https://thetiredwindow.com/bfaccountupdate/webhook",
  "event": "ACCOUNT_UPDATER_BATCH_UPDATES"
}

An HTTP 201 response indicates a successful request has been made. You will receive a response body containing a JSON object similar to the one below. The parameters returned are the same as in the request above but with the addition of the id parameter.

The id parameter value is the value you would provide for other calls that require a webhookID. This identifier is used for operations like retrieving, modifying, or removing a webhook, as we will see in the following examples.

Example Response Body:

{
  "url": "https://thetiredwindow.com/bfaccountupdate/webhook",
  "event": "ACCOUNT_UPDATER_BATCH_UPDATES",
  "id": "wbh_5249941f13564471b3be9f96a6d532c1"
}

Retrieving Webhook Details

To retrieve the details of a previously configured webhook you can send an HTTP GET request to the following end-point:

/api/v4/accounts/{accountId}/webhooks/{webhookID}

In the case of a successful request, you will receive an HTTP 200 response and a response body containing a JSON object containing the webhook's details.

If we were using the webhookID from the example above our end-point would be:

/api/v4/accounts/{accountId}/webhooks/wbh_5249941f13564471b3be9f96a6d532c1

And the response body would be a JSON object containing the details of the webhook.

Example Response Body:

{
  "url": "https://thetiredwindow.com/bfaccountupdate/webhook",
  "event": "ACCOUNT_UPDATER_BATCH_UPDATES",
  "id": "wbh_5249941f13564471b3be9f96a6d532c1"
}

Modifying a Webhook

To modify the details of a previously configured webhook you can send an HTTP PATCH request to the following end-point:

/api/v4/accounts/{accountId}/webhooks/{webhookID}

If we were using the webhookID from the previous examples above, our end-point would be:

/api/v4/accounts/{accountId}/webhooks/wbh_5249941f13564471b3be9f96a6d532c1

The request body would be a JSON object containing the parameters url and event.

Where the url property is the URL value you would like to receive your webhook notifications and the event property is the type of event that you would like to issue webhooks to your webhook.

For an Account Updater API webhook to work the only valid value for the event parameter is ACCOUNT_UPDATER_BATCH_UPDATES, so this probably wouldn't be something you would change.

Example Request Body:

{
  "url": "https://thetiredwindow.com/bfaccountupdate/new-webhook",
  "event": "ACCOUNT_UPDATER_BATCH_UPDATES"
}

In the case of a successful request, you will receive an HTTP 200 response and a response body containing a JSON object containing the webhook's details.

And the response body would be a JSON object containing the details of the webhook.

Example Response Body:

{
  "url": "https://thetiredwindow.com/bfaccountupdate/new-webhook",
  "event": "ACCOUNT_UPDATER_BATCH_UPDATES",
  "id": "wbh_5249941f13564471b3be9f96a6d532c1"
}

Deleting a Webhook

To delete a previously configured webhook you can send an HTTP DELETE request to the following end-point:

/api/v4/accounts/{accountId}/webhooks/{webhookID}

If we were using the webhookID from the previous examples above our end-point would be:

/api/v4/accounts/{accountId}/webhooks/wbh_5249941f13564471b3be9f96a6d532c1

In the case of a successful request, you will receive an HTTP 204 response.

Receiving Webhook Notifications

The following table outlines the parameters that are found within an Account Updater API webhook notification.

The following is an example JSON object body that would be sent as a webhook notification:

{
  
  "id"     : "not_5249941f13564471b3be9f96a6d532c1",
  "wbhid"  : "wbh_5249941f13564471b3be9f96a6d532c1",
  "event"  : "ACCOUNT_UPDATER_BATCH_UPDATES",
  "payload"  : {
      "updateId"  : "aupres_5249941f13564471b3be9f96a6d532c1",
      "url"    : "https://api.payconex.net/api/v4/accounts/{account}/account-updater/updates/{updateId}"
  }
}