Flixcheck provides two type of webhook events: notification and validation events. Through notification events, your application will be informed in real time about actions such as when a check is sent, opened, answered and rated. Through validation events, your application can decide whether the user input may be accepted or not, before Flixcheck continues to process it.

A webhook can be added in the Flixcheck portal by administrators at Settings > Webhooks. Note that the API plugin has to be activated on your account. Added webhooks have the following properties:

• URL The full URL of the webhook that will be called, starting with the protocol (http:// or https://). Note that for validation events, only https webhooks are allowed.

• Events Specifies for which events the webhook will be triggered. There are notification and validation events. If the event all is set, all notification events are triggered. We do not recommend this! Validation events have to be added explicitly.

• Headers Set specific headers that are used on the request, e.g. an Authorization or some custom X-MyCompany-Xyzheader.

• Custom Content

  Send additional information / values with the request. These will be included in a custom object in the request body with the specified custom key mapping to its corresponding value. For the values, placeholders may be used.

  {
      "event": "checkAnswered",
      "time": "2020-01-01T10:00:00Z",
      "content": {
          "accountId": "5a33da23c986d50e0be32177",
          "userId": "5a33da23c986d50e0be32178",
          "checkId": "5a72c00a787772072244396a",
          "alreadyAnswered": false,
          "custom": {
              "username": "Martina Mustermann",
              "department": "Sales"
          }
      }
  }
  

• Custom Content (Request Body)

  Alternatively, you can also completely replace the standard request body to match your expected API definitions and be unaffected by changes in the request body interfaces.

  This allows you to send only specified data with the request. Be aware that doing so means additional information that would be sent via the standard request body will be lost, so include all relevant information explicitly in your custom body.

  The content-format of the body is freely choosable. You can use JSON annotation, XML or others. Please note that in order for your application to correctly detect the content type, you will need to set the corresponding HTTP-Header. For example, if you use the JSON format, you will need to set the HTTP-Header Content-Type: application/json.

  Inside the custom body, placeholders may be used. In this case, an additional placeholder called webhookevent will be available which points to the event causing the webhook to trigger.

  Here is an example of a custom body:

  {
  		"event": "{{ wehookevent }}",
      "team": "Management IT",
      "checkId": "{{ checkid }}",
  		"version": 2,
      "additionalInfo": {
  			"recipient": "{{ recipient }}"
  		}
  }
  

• Timeout optional Set a timeout to wait for in ms. Note that longer timeouts may have a negative impact on the user experience, since the Flixcheck-processing of the user input starts after your answer.

• Certificates optional When using an HTTPSendpoint, you can specify your own self-signed public certificate(s) to be trusted when establishing the TLS connection. Note that the standard CA certificates are disabled if you manually set your own certificate(s). You can also set your own root certificate and use a certificate signed by that root certificate on your responses.

• Continue on Validation Errors optional If activated, the user input will be processed if there is an error while getting the validation response or if the validation response status code is 5xx.

• Limit Validations optional If activated, the number of validations per check per minute is limited to 5. Whether the limit is reached is calculated for every check-ip-combination.

• Authentication optional Authentication options are OAuth2 and mTLS.

  • OAuth2

    1. You set up the OAuth2 credentials → when a webhook request should be sent, our backend catches a token from your OAuth2 endpoint
       • Authentication-Types for OAuth2 Authentication are client_credentials, password and jwt
    2. You use the OAuth2 token → set it in your header or body

       • The Access-Token can be used in the Additional-Headers section with the replace token {{ oauth_token }}

         Authorization: Bearer {{ oauth_token }}
         

  • mTLS

    • When using mTLS, both sides will use a private/public-keypair to encrypt and sign their requests and responses.
    • Therefore, the trusted certificates need to be exchanged. This can be managed via the mTLS settings panel.
    • The requests themselves will be encrypted/signed by leaf certificates with limited lifetime. To prevent overhead with the configuration whenever a leaf certificate (on one of both sides) changes, we recommend trusting our CA certificate and that you configure us to trust your CA or intermediate certificate.

All webhook calls will be HTTP POST requests to your provided URL. The content will be a UTF-8 encoded JSON object. Your answer will also be interpreted as JSON object.

// Example JSON object
{
  "event": "checkOpened",
  "time": "2023-12-05T06:03:34.341Z",
  "content": {
    "checkId": "6583d5215b2b2e04e6eeafef",
    "userId": "5a33da23c986d50e0be32178",
    "accountId": "5a33da23c986d50e0be32177",
    "alreadyOpened": true
  }
}

Failure Handling and Pausing

If a webhook fails too frequently, it will automatically be paused. While paused, no webhook requests will be sent, and all events will be queued in the backlog. To resume operations, the webhook must be manually reactivated. However, if the webhook exceeds the failure threshold again after reactivation, it will be paused once more.

Both failed webhook attempts and all requests that would have been sent during the paused state are logged in the system. This allows you to review and analyze all interactions, even those missed during downtime.

Configuring the Failure Threshold

You can define the number of failures after which the webhook will be paused: