# Manage webhooks

Set up and process webhook notifications.

## Set up webhooks

To set up a default URL for all webhooks:

1. In the Unity Portal, go to **Merchant setup > Merchant groups**.
2. Select a merchant group.
3. Click the **Webhooks** tab.
4. Enter the URL you want PXP to send notifications to and generate a hash key.
5. Click **Save** to confirm. Your webhooks are now set up.


You can also override the merchant group settings and use a different URL for a specific merchant. To do so, select a merchant and go to the **Webhooks** tab and enter your URL. This works at both the default (overall) level and the service level.

To set up a URL for a specific service:

1. In the Unity Portal, go to **Merchant setup > Merchant groups**.
2. Select a merchant group.
3. Click the **Webhooks** tab.
4. Enter the URL you want PXP to send notifications to.
5. Optionally, tick the box next to the types of events you want PXP to use this URL for. If no box is ticked, PXP will send all the notifications related to the service to your chosen URL.
6. Click **Save** to confirm. Your webhook URL is now updated.


## Process a webhook

/v1/merchant-webhooks

To process a webhook, you'll need to supply key data from the webhook notification that you received:

* The `eventDate`: The date and time that the event occurred at, in ISO 8601 format.
* The `eventCategory`: The specific area of payment operations that the event belongs to. One of: `Authentication`, `Token`, `Transaction`, or `Reporting`.
* The `eventData`: Details about the event. The structure of this object varies depending on the event. See [About webhooks](/guides/get-started/about-webhooks) for more information.


### Request example

The following example shows how to process a webhook notification for a *Transaction authorised* event.


```curl
curl --request POST \
     --url https://api-services.pxp.io/api/v1/merchant-webhooks \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "eventDate": "2024-10-27T08:51:04.8264455Z",
    "eventCategory": "Transaction",
    "eventData": {
      "state": "Authorised",
      "approvalCode": "123456",
      "merchant": "MERCHANT-1",
      "site": "SITE-1",
      "transactionMethod": {
        "intent": "Authorisation",
        "fundingType": "Card",
        "entryType": "Ecom"
      },
      "amounts": {
        "transactionValue": 50.05,
        "currencyCode": "EUR"
      },
      "merchantOrderId": "merchant_order_id",
      "merchantTransactionId": "merchant_transaction_id",
      "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
      "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
      "fundingData": {
        "cardScheme": "Visa",
        "tokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
        "schemeTokenNumber": "4837261112345678",
        "providerResponse": {
          "provider": "PXPFinancial",
          "code": "00",
          "message": "Approved",
          "merchantId": "77772182",
          "addressVerificationServiceResult": "D",
          "cardVerificationCodeResult": "A",
          "schemeTransactionId": "TX1234567890123456",
          "paymentAccountReference": "PAR12345678901234567890",
          "electronicCommerceIndicatorAdjustment": "01",
          "settlementDate": "2024-01-25"
        }
      }
    }
  }
]
'
```

### Response example

If your request is successful, you'll receive a `200` response.


```json
{
  "state": "Success"
}
```

For more information about this endpoint, [see the API reference](/apis/merchant-webhook).

## Manage duplicates

In some cases, you might receive the same webhook event twice — so make sure that your system is able to deal with duplicates. These duplicate webhook events will have the same values in the `eventCode` and `systemTransactionId` fields, while the `eventDate` and other fields can be different. Your server should always use the details from the latest webhook event.