Webhooks

Webhooks let you set up connections between third party platforms or apps with real time information regarding certain events. When one of those events is triggered, we’ll send a HTTP POST request with JSON payload to the configured webhook URL.

Each webhook request sent by SEON is cryptographically signed to ensure the integrity and authenticity of the payload. The payload is signed using the HMAC-SHA256 algorithm. The signing key is the customer's license key, and the signature is sent in the Digest header. An example of this header would be the following: Digest: SHA-256=<hash>. To verify the digest, please hash the whole HTTP payload using the HMAC-SHA256 algorithm and compare it to the hash provided in the Digest header.

Our webhooks are delivered in most cases but should there be a failure, we don’t retry or queue the request.

You can set up the events and webhook URLs in the Admin Panel of your Settings page.

Available events

Event	Description
transaction:status_update	Any time a transaction state has changed.
lists:blacklist-whitelist	Any value has been added to blacklist or whitelist or removed from them.
lists:customlist	Any value has been added to Custom lists or removed from them.
aml:person_updates	Any value has been changed during a person's AML monitoring.
aml:entity_updates	Any value has been changed during an entity's AML monitoring.

How Webhook Secrets Work at SEON

This section outlines the functionality and handling of Webhook secrets within SEON, clarifying their relationship with API Keys and their visibility across different environments.

Sandbox vs Live

For each Customer account, SEON maintains 2 separate environments - Sandbox and Live Production.

Each environment operates with its own distinct set of keys. This is true for both API integrations and Webhooks.

License Key vs API Key

License Keys and API Keys are different entities within SEON's system, however, they are initially the same when a new production or sandbox customer account is created.

API Key: used for API integrations
- A single production/sandbox account can have multiple API Keys
- Can be deleted and regenerated
License Key: used for Webhooks
- 1 for each production/sandbox account
- Cannot be changed
- Upon account creation, is the same as the initial API Key

Visibility of Keys

The visibility of API Keys and License Keys (Webhook Secrets) varies depending on the user interface and account type.

Public Admin Panel

API Keys
- Both Production and Sandbox API Keys are displayed under Settings -> Organization -> API License Keys
License Keys (Webhook Secret)
- For Production accounts, the License Key (Webhook Secret) is shown under Settings -> Organization -> Details

Testing Webhooks Vs. Production Usage

Sandbox Testing: When testing webhooks in sandbox, use your sandbox API key for both transaction operations AND webhook digest validation

Production: When using production webhooks, use your production API key for both transaction operations AND webhook digest validation.

The API Keys mentioned above can be found under the Settings → API License Keys section

{
  "event": "transaction:status_update",
  "date": "2017-08-30T13:47:42+00:00",
  "transactions": [
    {
      "id": "e601f2dae8f9",
      "state": "REVIEW",
      "label": "Marked as review"
    }
  ]
}

{
  "event": "lists:blacklist-whitelist",
  "date": "2017-08-30T13:47:42+00:00",
  "values": [
    {
      "data_field": "user_id",
      "value": "111",
      "state": "blacklist"
    },
    {
      "data_field": "user_id",
      "value": "222",
      "state": "whitelist"
    },
    {
      "data_field": "user_id",
      "value": "333",
      "state": "normal"
    }
  ]
}

 {
  "event": "lists:customlist",
  "date": "2017-08-30T13:47:42+00:00",
  "values": [
    {
    "data_field": "user_id",
    "value": "413132231",
    "state": "watchlist"
    },
    {
    "data_field": "user_id",
    "value": "3243112",
    "state": "custom_sample_list"
    }
   ]
 }

{
   "event":"aml:person_updates",
   "date":"2017-08-30T13:47:42+00:00",
   "values":[
      {
         "hash":"9d42a989bffc31bd1330a36229f4aa2e480be4de65ecfa291b896baaf73938a2",
         "user_id":"212313213",
         "status":"REOPENED",
         "changes":[
            "pep",
            "sanctionlist",
            "watchlist",
            "crimelist"
         ]
      }
   ]
}

{
   "event":"aml:entity_updates",
   "date":"2017-08-30T13:47:42+00:00",
   "values":[
      {
         "hash":"9d42a989bffc31bd1330a36229f4aa2e480be4de65ecfa291b896baaf73938a2",
         "user_id":"212313213",
         "status":"REOPENED",
         "changes":
            "sanctionlist",
            "watchlist"
         ]
      }
   ]
}