Insights Webhooks

Insight groups are configured for each merchant in the Internal Portal, allowing merchants to then freely turn on Webhooks for those groups within the Admin Dashboard.

Webhooks are a crucial mechanism for merchants to receive notifications about Insight Groups.

Webhook processing and Security

Yaspa Webhooks are sent via HTTPS and are signed with SHA256withRSA. For information on processing and around Webhook security see the section here - Webhooks.

Client implementations must not use strict mode parsing on the JSON payload. The webhook body may contain additional, optional parameters not explicitly listed here, and strict parsing will result in deserialisation failures.

Insights Webhook payload and Parameters

The Insights webhook is HTTPS post request and a typical example of the request body is as follows:

{
  "type": "INSIGHTS",
  "data": {
    "metadata": {
      "merchantId": "684af205b26c48042487c93c",
      "customerId": "eixyc0oxx9o0",
      "reference": "eixyc0oxx9o0",
      "citizenTransactionId": "54f97545-a987-cfa9-b2a8-f66b97",
      "merchantTradingName": "Test Merchant"
    },
    "insightGroup": {
      "id": "68d6593704a1aa70943d2bb1",
      "name": "Payment Basics",
      "insights": [
        "PAYMENT_BASICS"
      ],
      "period": [
        "MONTHLY"
      ],
      "fromDate": "2025-06-28T09:32:33.440188Z",
      "toDate": "2025-07-26T09:32:33.440206Z"
    },
    "insights": {
      "PAYMENT_BASICS": {
        "insight": "PAYMENT_BASICS",
        "fromDate": "2025-06-28T09:32:33.440188Z",
        "toDate": "2025-07-26T09:32:33.440206Z",
        "accounts": [
          {
            "accountId": "9800b595-329f-49ff-8519-b6d5622f211f",
            "accountType": "CURRENT",
            "currency": "GBP",
            "closingBalance": 350,
            "lastUpdatedAt": "2025-09-26T09:32:33.852805Z",
            "consents": [
              {
                "consentId": "31d99e03-2ae2-40db-a39b-50b2fb650581",
                "status": "ACTIVE",
                "createdAt": "2025-07-26T09:32:33.126Z",
                "expiresAt": "2025-10-25T10:32:33.125Z"
              }
            ],
            "paymentBasics": {
              "categorisations": {
                "OTHER": {
                  "PAYOUT": {
                    "paymentCount": 15,
                    "amount": 200
                  },
                  "PAYIN": {
                    "paymentCount": 5,
                    "amount": 300
                  }
                },
                "GAMBLING": {
                  "PAYOUT": {
                    "paymentCount": 6,
                    "amount": 150
                  },
                  "PAYIN": {
                    "paymentCount": 2,
                    "amount": 40
                  }
                }
              },
              "period": {
                "MONTHLY": [
                  {
                    "fromDate": "2025-06-28T09:32:33.440188Z",
                    "toDate": "2025-06-30T23:59:59Z",
                    "description": "2025-06",
                    "data": {
                      "OTHER": {
                        "PAYOUT": {
                          "paymentCount": 10,
                          "amount": 170
                        },
                        "PAYIN": {
                          "paymentCount": 3,
                          "amount": 200
                        }
                      },
                      "GAMBLING": {
                        "PAYOUT": {
                          "paymentCount": 2,
                          "amount": 50
                        },
                        "PAYIN": {
                          "paymentCount": 1,
                          "amount": 20
                        }
                      }
                    }
                  },
                  {
                    "fromDate": "2025-07-01T00:00:00Z",
                    "toDate": "2025-07-31T23:59:59Z",
                    "description": "2025-07",
                    "data": {
                      "OTHER": {
                        "PAYOUT": {
                          "paymentCount": 5,
                          "amount": 30
                        },
                        "PAYIN": {
                          "paymentCount": 2,
                          "amount": 100
                        }
                      },
                      "GAMBLING": {
                        "PAYOUT": {
                          "paymentCount": 4,
                          "amount": 100
                        },
                        "PAYIN": {
                          "paymentCount": 1,
                          "amount": 20
                        }
                      }
                    }
                  }                  
                ]
              }
            }
          }
        ]
      }
    }
  }
}

Insight webhook payload contains common data fields applicable to all insights, along with a nested object structure that contains the specific data for each insight type included in the group.

Insights

Insight Data

Metadata

Insight Group

There will often be other parameters in the body, such as some of the optional parameters will be carried through the system, as such it's critically important that merchant servers do not use strict mode parsing on the above JSON format, otherwise there will be failures to read data from Yaspa.

Parameter list: