---
title: Webhooks
slug: webhooks
docTags: 
createdAt: 2024-07-08T14:35:48.492Z
---

Webhooks are an optional secure service provided by Judopay to use to notify your system, typically delivering the webhook message a **sub-second after a transaction or event has taken place.**

:::hint{type="warning"}
The webhook message will make **four attempts **to be delivered. 
Following this, the message will fail to deliver and be dropped.
:::

The benefit of using webhooks means you do not need to pull information from the Judopay API for every event.

***

## Example Webhook Model

:::hint{type="warning"}
If you set up webhooks for transaction status updates, be aware this is a separate, independent service from using the configured `successUrl` / `cancelUrl` redirects as described in [Configuring redirect URLs](docId\:GloRwwwFKFqp34FyKCXe8).
:::

Data is passed in a POST call to your webhook URL with:

- Header: `Content-Type: application/json` 
- Message content: The schema of the receipt block is the same as received from direct transaction responses.

The example below shows the message content:

:::CodeblockTabs
Example Webhook Message Content

```json
{
    "receipt": {
        "receiptId": "1333739148921700352",
        "yourPaymentReference": "34a73594-f3b2-414c-a5c9-58679530b418",
        "type": "Payment",
        "result": "Success",
        "judoId": 100502814,
        "originalAmount": "5.00",
        "netAmount": "5.00",
        "amount": "5.00",
        "currency": "GBP",
        "cardDetails": {
            "cardLastfour": "1111",
            "endDate": "1228",
            "cardToken": "SOF-xFmZmEnoR_Sj9mtrCvrxhw",
            "cardType": 1,
            "cardScheme": "VISA",
            "cardFunding": "Credit",
            "cardCategory": "",
            "cardCountry": "US",
            "bank": "JPMORGAN CHASE BANK, N.A."
        },
        "cardAddress": {
            "address1": "CardHolder House",
            "address2": "1 CardHolder Street",
            "town": "CardHolder Town",
            "postCode": "AB1 2CD",
            "countryCode": 826
        },
        "consumer": {
            "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408"
        }
    }
}
```
:::

It is recommended you create a script to retrieve the data from the **content **parameter in the receipt model.

:::hint{type="info"}
The data can then be parsed and used as normal.
:::

***

### Enable Webhooks

:::hint{type="danger"}
To receive webhooks you are required to use **TCP Port 443**.
:::

**From the Judopay Portal**:

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/MSRL-Rt-yoyKV1rCRGYZr-20260511-120136.png" size="84" width="1232" height="1284" position="center" alt="enable webhooks" darkWidth="1232" darkHeight="1284" showCaption="false"}

:::::WorkflowBlock
:::WorkflowBlockItem
From the side menu, select **Your apps.**
:::

:::WorkflowBlockItem
Select the app you wish to edit.
*For the purpose of this exercise, **Webhooks App** is selected.*
:::

:::WorkflowBlockItem
Select **Webhooks configuration.**
:::

:::WorkflowBlockItem
The Webhooks configuration screen apears.

Select the Webhooks for your required transaction type(s):

- Enable Webhooks Payment
- Enable Webhooks Collection
- Enable Webhooks PreAuth
- Enable Webhooks Refund

Add your Webhooks URL.
:::

:::WorkflowBlockItem
Click **Add authentication.**
:::

:::WorkflowBlockItem
The Add authentication screen appears.
:::

::::WorkflowBlockItem
Confirm and click **Add authentication.**

:::hint{type="warning"}
Webhooks will not work until you add the **authentication**.
:::

Your unique username and password for authentication will be displayed.
The username and password will be combined with a colon separating them and will be encoded using Base64.
::::

:::WorkflowBlockItem
Click **Save Webhooks.**
The selected Webhooks will now be authenticated using this method.
Judopay will send this username and password along with every request.
:::
:::::

:::hint{type="info"}
If you have any issues enabling webhooks, contact [Customer Support](mailto\:help@judopay.com) and provide the **notificationUrl**.
This is the URL where you would like Judopay's Transaction API to **POST **the webhook message to.
:::