Setting up and Managing Webhooks

Overview

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

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

When a card is updated that is associated with one of your subscriptions, you will get a notification to your webhook URL with the details.

It is important to note that when webhooks are triggered, the event name triggers them all. In other words, if you have multiple webhooks under the same event name, they are all triggered simultaneously. This means that each webhook configured for that event receives the payload, which can be useful for executing multiple actions in response to a single event. However, it also requires careful management to ensure that each webhook handles the payload appropriately and that the simultaneous processing does not cause unintended side effects or performance issues.

📘

Testing the Webhooks

In the following examples, we configured our own webhook URLs to trigger PAYCONEX_BATCH_SETTLEMENT or ACCOUNT_UPDATER_BATCH_UPDATES. Besides being useful for testing purposes (while in the certification environment), this also helps you get started quickly with the Webhook API. For suggestions on the webhook tools that are best to use, please reach out to our Bluefin Technical Team.

Webhook Events

Creating a Webhook

The request body is a JSON object containing the parameters url and event. The url property is the URL at which 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.

Request

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

{
  "url": "https://mywebhookexample5921cad3-24e4-47d4-bf88-438b9a6a77a9.com",
  "event": "ACCOUNT_UPDATER_BATCH_UPDATES"
}

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 deleting a webhook.

Response

{
  "url": "https://mywebhookexample5921cad3-24e4-47d4-bf88-438b9a6a77a9.com",
  "event": "ACCOUNT_UPDATER_BATCH_UPDATES",
  "id": "wbh_5249941f13564471b3be9f96a6d532c1"
}

Triggering a Webhook

Triggering a webhook manually is useful for verifying that your webhook works correctly. This allows you to test and debug the webhook's functionality, ensuring that it correctly receives and processes the payload as expected before it is deployed it in a live environment.

🚧

Note

The only type of webhook you can trigger manually is PAYCONEX_BATCH_SETTLEMENT. Before triggering it, ensure that you have created a webhook with the PAYCONEX_BATCH_SETTLEMENT event.

Request

POST /api/v4/webhooks/trigger

{
  "account_id": "220615031547",
  "event": "PAYCONEX_BATCH_SETTLEMENT",
  "batch_id": "00412",
  "batch_date": "2024-06-27 17:27"
}

*Required Scopes: pcx:webhooks:*, pcx:webhooks:trigger

Since this is a batch settlement, batch_id and batch_date are included here.

Retrieving Webhook Details

To retrieve the details of a previously configured webhook, you can send a HTTP GET request to the following endpoint:

Request

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

*Required Scopes: pcx:webhooks:*, pcx:webhooks:read

Response

{
  "url": "https://mywebhookexample5921cad3-24e4-47d4-bf88-438b9a6a77a9.com",
  "event": "ACCOUNT_UPDATER_BATCH_UPDATES",
  "id": "wbh_5249941f13564471b3be9f96a6d532c1"
}

Getting a List of Webhooks

To get the full list of the webhooks under your accoundId with the ids that you can use to apply operations like retrieving, modifying, or deleting a webhook, make a request to the following endpoint:

Request

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

*Required Scopes: pcx:webhooks:*, pcx:webhooks:read

Response

[
  {
    "id": "wbh_9e64186ebddf484ea89bb06653a8fa08",
    "event": "PAYCONEX_BATCH_SETTLEMENT",
    "url": "https://mywebhookexample5921cad3-24e4-47d4-bf87-438b9a6a77a9.com"
  },
  {
    "id": "wbh_2e7eeb3bb00d4a3c97d75ba0dd5d6203",
    "event": "ACCOUNT_UPDATER_BATCH_UPDATES",
    "url": "https://mywebhookexample5921cad3-24e4-47d4-bf88-438b9a6a77a9.com"
  },
  {
    "id": "wbh_e598bfc6bdc244558e6278c4e145468e",
    "event": "PAYCONEX_BATCH_SETTLEMENT",
    "url": "https://mywebhookexample5921cad3-24e4-47d4-bf89-438b9a6a77a9.com"
  }
]

Modifying a Webhook

A HTTP PATCH request modifies the details of a previously configured webhook.

The request body is a JSON object containing the parameters url and event where the url property is the URL value where 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.

Be aware that 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 unless you wanted it to be PAYCONEX_BATCH_SETTLEMENT.

Request

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

{
  "url": "https://mywebhookexample6921cad3-24e4-47d4-bf88-438b9a6a77b9.com",
  "event": "ACCOUNT_UPDATER_BATCH_UPDATES"
}

*Required Scopes: pcx:webhooks:*, pcx:webhooks:update

If the request is successful, you receive a HTTP 200 response and a response body containing a JSON object which in turn contains the webhook's details.

The response body is a JSON object containing the details of the webhook.

Response

{
  "url": "https://mywebhookexample6921cad3-24e4-47d4-bf88-438b9a6a77b9.com", // new webhook target URL
  "event": "ACCOUNT_UPDATER_BATCH_UPDATES",
  "id": "wbh_5249941f13564471b3be9f96a6d532c1"
}

Deleting a Webhook

To delete a previously configured webhook, send a HTTP DELETE request to the following endpoint:

Request

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

*Required Scopes: pcx:webhooks:*, pcx:webhooks:delete

If the request is successful, you receive a HTTP 204 No Content response.

Receiving Webhook Notifications

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

Notification Example

The following is an example JSON object body that could 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}"
  }
}