Configuring webhooks

Enable webhooks to get a real time notification when something happens in PassFort.

What are webhook events?

Every webhook is triggered by an event in PassFort. Different webhooks send callbacks for different events.

When a webhook is triggered by an event, it sends a callback to an endpoint you choose. The callback contains key information about what change occurred.

You can enable webhooks for the following events.

Product status changed

When this webhook event is enabled, you'll receive a callback whenever the product status on an application changes (e.g. an application has gone from Approved to In review).

Callbacks have these important keys:

  • secret: Authenticate the request by ensuring this secret matches your secret.
  • new_status: The new status of the application.
  • data.product.alias: The alias of the product which the application is for.
  • data.profile_id: The ID of the profile that made the application.
  • user: An object that contains details of the user who changed the status. If the smart policy changed the status, the value is null.

In this example, a callback was sent because a user, Morgan Rose, manually cancelled a profile's application for a product called Forexo Basic Account.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "PRODUCT_STATUS_CHANGED",
"secret": "yourSecret",
"timestamp": 1568997222,
"data": {
"apikey": {
"name": "KEY_NAME"
},
"application_id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"customer_ref": null,
"new_status": "CANCELLED",
"product": {
"alias": "forexo_basic",
"id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"name": "Forexo Basic Account"
},
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
"user": {
"email": "morgan.rose@forexo.com",
"id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
"name": "Morgan Rose"
}
}
}

For an example of when you may want to use this, see Tracking the status.

Check completed

When this webhook event is enabled, you'll receive a callback whenever results are returned from a check. If an error occurs when a check is run, this is returned as well.

Callbacks have these important keys:

  • secret: Authenticate the request by ensuring this secret matches your secret.
  • data.check.check_type: The type of check that was run. To learn about the different check types, see What are PassFort's checks?
  • data.check.variant.alias: The alias for the check variant.
  • data.check.result: The result of the check (e.g. Pass, Fail, Error). The possible results for a check depends on the data provider and configuration options used for the check variant. To get the possible results, see the configuration article for your data provider.

In this example, a variant of the Electronic identity check was run on an application and it failed.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "CHECK_COMPLETED",
"secret": "yourSecret",
"timestamp": 1569509539,
"data": {
"check": {
"check_type": "IDENTITY_CHECK",
"id": "ea565b55-47d9-1858-4588-3a22a3838707",
"result": "Fail",
"variant": {
"alias": "onfido_identity_check",
"id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
"name": "Onfido"
}
},
"customer_ref": null,
"profile_id": "4f434848-e060-11e9-8fea-12bd74fbd3fc"
}
}

For an example of when you may want to use this, see Getting check results.

Product badge changed

When this webhook event is enabled, you'll receive a callback whenever the application processing state (also known as the "flag") changes.

Callbacks have these important keys:

  • secret: Authenticate the request by ensuring this secret matches your secret.
  • new_flag: The new application flag.
  • new_status: The status of the application. Note that it may not have changed since the flag was last updated.
  • data.product.alias: The alias of the product which the application is for.
  • data.profile_id: The ID of the profile that made the application.
  • user: An object that contains details of the user who changed the status. If the smart policy changed the status, the value is null.

In this example, the callback was sent because a user, Morgan Rose, manually added a new product application for a product called Forexo Basic Account to a profile. We can tell it's a new application because the new_status is APPLIED, and we can tell that the smart policy is being applied because the new_flag is AUTOMATING.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "PRODUCT_BADGE_CHANGED",
"secret": "yourSecret",
"timestamp": 1569503987,
"data": {
"apikey": {
"name": "KEY_NAME"
},
"application_id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"customer_ref": null,
"new_flag": "AUTOMATING",
"new_status": "APPLIED",
"product": {
"alias": "forexo_basic",
"id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"name": "Forexo Basic Account"
},
"profile_id": "4f434848-e060-11e9-8fea-12bd74fbd3fc",
"user": {
"email": "morgan.rose@forexo.com",
"id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
"name": "Morgan Rose"
}
}
}

For an example of when you may want to use this, see Displaying the application processing state.

Risk level changed

When this webhook event is enabled, you'll receive a callback whenever the application risk level has changed.

This webhook event is only applicable if you're using the Risk module.

Callbacks have these important keys:

  • secret: Authenticate the request by ensuring this secret matches your secret.
  • data.old_category: The application's risk level before it was changed.
  • data.new_category: The application's risk level after it was changed.
  • data.product.alias: The alias of the product which the application is for.
  • data.profile_id: The ID of the profile that made the application.

In this example, an application for a product called Forexo Basic had an Undetermined risk level that changed to a Low risk level.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "RISK_LEVEL_CHANGED",
"secret": "yourSecret",
"timestamp": 1569244762,
"data": {
"application_id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"customer_ref": null,
"new_category": "LOW",
"old_category": "UNDETERMINED",
"product": {
"alias": null,
"id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"name": "Forexo Basic Account"
},
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}

For an example of when you may want to use this, see Syncing risk levels.

Task state changed

A task has gone from incomplete to passed/failed or a task has gone from passed/failed to incomplete.

Tasks can have these states:

  • COMPLETED_PASS: The task has passed.
  • COMPLETED_FAIL: The task has failed.
  • INCOMPLETE: The task is incomplete.

Callbacks have these important keys:

  • secret: Authenticate the request by ensuring this secret matches your secret.
  • data.profile_id: The profile ID of the profile that has the changed task.
  • data.new_state: The state of the task after the change.
  • data.applications: The profile's applications that use the changed task.
  • data.task: The task that was changed. Use data.task.variant.alias to find the task's alias.
  • data.user: The user that updated the task's state. If the task state was updated by the smart policy or via the API, the value will be null.

In this example, a user named Morgan Rose passed the Verify identity task. This task is used for the application to the Forexo Basic Account product.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "TASK_STATE_CHANGED",
"secret": "yourSecret",
"timestamp": 1567009086,
"data": {
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
"customer_ref": "123456",
"new_state": "COMPLETED_PASS",
"applications": [
{
"id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"product": {
"id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"alias": "forexo_basic",
"name": "Forexo Basic Account"
},
"status": "APPLIED"
}
],
"task": {
"id": "3d7a333c-418d-72a1-007b-06854dbb28eb",
"type": "INDIVIDUAL_VERIFY_IDENTITY",
"is_complete": "true",
"is_expired": "false",
"state": "COMPLETED_PASS",
"variant": {
"id": "verify_identity",
"alias": "null",
"name": "Verify identity"
}
},
"user": {
"email": "morgan.rose@forexo.com",
"id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
"name": "Morgan Rose"
},
"apikey": {
"name": "API Key Name"
}
}
}

Collected data updated

When this webhook event is enabled, you'll receive a callback whenever a profile's collected_data changes in PassFort.

The webhook callback contains a copy of the new data and the old data so you can see what's changed.

Callbacks have these important keys:

  • secret: Authenticate the request by ensuring this secret matches your secret.
  • data.old_data: An object that contains all the information that was in the profile’s collected_data before it was changed.
  • data.new_data: An object that contains all the information that's in the profile’s collected_data after the changes (including information that hasn't changed).
  • data.profile_id: The profile ID of the profile that was changed.

In this example, a date of birth was added to an individual profile.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "COLLECTED_DATA_UPDATED",
"secret": "yourSecret",
"timestamp": 1567009086,
"data": {
"apikey": {
"name": "API Key Name"
},
"customer_ref": null,
"new_data": {
"entity_type": "INDIVIDUAL",
"personal_details": {
"dob": "1975-04-19",
"name": {
"family_name": "Wheeler",
"given_names": [
"Alex",
"D"
]
}
}
},
"old_data": {
"contact_details": {},
"entity_type": "INDIVIDUAL",
"personal_details": {
"name": {
"family_name": "Wheeler",
"given_names": [
"Alex",
"D"
]
}
}
},
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
"user": null
}
}

For an example of when you may want to use this, see Update your system data when PassFort's profile data changes.

Form state changed

When this webhook event is enabled, you'll receive a callback whenever the state of a custom form has changed (e.g. it was created, submitted, or approved).

Forms can have these states:

  • INSTANTIATED: The form instance has been created, but it's not ready to be filled by a user.
  • SENT: The form instance is ready to be filled by a user.
  • SUBMITTED: The form instance has been filled and submitted by a user, but it has not yet been accepted by PassFort.
  • ACCEPTED: The form instance has been submitted, and PassFort or a user has accepted the form contents.
  • COMPLETED: The form lifecycle has completed, and the collected data has been processed by PassFort.
  • EXPIRED: The form was not completed before its expiry period or was manually marked as expired, and it can no longer be completed.

Callbacks have these important keys:

  • secret: Authenticate the request by ensuring this secret matches your secret.
  • profile_id: The unique identifier of the profile that has the form.
  • form_id: The unique identifier for the form that was changed.
  • data.old_state: The state of the form before it was changed. When a new form instance is created, the old_state is null.
  • data.new_state: The state of the form after it was changed.
  • data.user: An object that contains information about the user who made the change.

In this example, a user named Morgan Rose has submitted a form. The form has not yet been accepted.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "FORM_STATE_CHANGED",
"secret": "yourSecret",
"timestamp": 1567009086,
"data": {
"new_state": "SUBMITTED",
"old_state": "SENT",
"template_id": "a7a57663-8d1b-c45b-73e2-19616ce0ebe5",
"form_id": "913c68e8-c246-463d-b59b-78c4444647b9",
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
"user": {
"email": "morgan.rose@forexo.com",
"id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
"name": "Morgan Rose"
},
"apikey": {
"name": "API Key Name"
}
}
}

Manual action required

When this webhook event is enabled, you'll receive a callback whenever a profile's application requires manual action to progress to the next status.

This event sends callbacks in the following circumstances:

  • The risk score or level cannot be calculated, so additional profile data needs to be added. If you're using the legacy version of smart policies, the callback is sent whenever the risk score or level can't be calculated. If you're using the new smart policies, the callback is only sent when the application reaches a branch that uses the risk score or risk level property.
  • The smart policy cannot choose a branch path for the application until it has more data. For example, when the application reaches a branch that uses the country of address property and the profile doesn't have a country of address. Note that only the new smart policies have branches, so the callback will only be triggered for this reason when you're using the new smart policies.
  • The smart policy has completed all automated processes, and tasks need to be completed manually or the application needs to be decided (approved, rejected, cancelled) manually.
  • A task is passed or failed manually, and either more tasks need to be completed manually or the application needs to be decided manually.
  • The application is decided, and no further manual actions are required.
If the profile does have data for the required risk score, it's possible your risk model needs to be updated to include a rule that can handle the profile's data. For example, if the risk model does not assign any risk score when the profile's country of residence is outside Europe or North America, the UPDATE_RISK_SCORE_DATA action_type will be returned if a profile's country of residence is China.

Callbacks have these important keys:

  • secret: Authenticate the request by ensuring this secret matches your secret.
  • data.profile_id: The ID of the profile that made the application.
  • data.actions: An array of objects where each object corresponds to a manual action. When the application has been decided and there are no manual actions left, the callback returns an empty array. Note that if multiple tasks on an application are incomplete, the array has one object for each incomplete task
  • data.actions.action_type: The type of manual action required. These are the possible values:
    • UPDATE_RISK_SCORE_DATA: Returned when the risk score or level cannot be calculated.
    • UPDATE_REQUIRED_DATA: Returned when the smart policy requires additional data.
    • COMPLETE_REQUIRED_TASK: Returned when a task needs to be completed.
    • REVIEW_APPLICATION: Returned when the application needs to be decided.
  • data.actions.product.alias: The alias of the product which the application is for.
  • data.actions.task.variant.alias: The alias of the task that requires action. Note that this key is only returned when the action_type is COMPLETE_REQUIRED_TASK.
  • data.actions.task.state: The state of the task that requires action. Note that this key is only returned when the action_type is COMPLETE_REQUIRED_TASK.

In the following example, the risk score or risk level could not be calculated for an application for a product called Forexo Basic Account. We can see the issue is with the risk score or risk level because the action_type is UPDATE_RISK_SCORE_DATA.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "MANUAL_ACTION_REQUIRED",
"secret": "yourSecret",
"timestamp": 1569417715,
"data": {
"actions": [
{
"action_type": "UPDATE_RISK_SCORE_DATA",
"applications": [
{
"id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"product": {
"alias": "forexo_basic",
"id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"name": "Forexo Basic Account"
},
"status": "APPLIED"
}
],
"due": "NOW"
}
],
"customer_ref": null,
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}
To find out what data is required for the risk score or risk level, see Learn which data is required.

In this next example, the application is stuck at a branch in the smart policy because more data is required. We can see the issue is with the risk score or risk level because the action_type is UPDATE_REQUIRED_DATA.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "MANUAL_ACTION_REQUIRED",
"secret": "yourSecret",
"timestamp": 1569417715,
"data": {
"actions": [
{
"action_type": "UPDATE_REQUIRED_DATA",
"applications": [
{
"id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"product": {
"alias": "forexo_basic",
"id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"name": "Forexo Basic Account"
},
"status": "APPLIED"
}
],
"due": "NOW"
}
],
"customer_ref": null,
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}
To find out what data is required for the branch, see Learn which data is required.

In the following example, the action_type is COMPLETE_REQUIRED_TASK, so we know the application needs to have at least one task completed before it can be approved. The task that needs to be completed has the verify_address alias, and we know that it's the only task that needs to be completed right now because it's the only object in the actions array.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "MANUAL_ACTION_REQUIRED",
"secret": "yourSecret",
"timestamp": 1569417715,
"data": {
"actions": [
{
"action_type": "COMPLETE_REQUIRED_TASK",
"applications": [
{
"id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"product": {
"alias": "forexo_basic",
"id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"name": "Forexo Basic Account"
},
"status": "APPLIED"
}
],
"due": "NOW",
"task": {
"id": "72aadb55-8b02-8495-d6b0-e1627ec23612",
"state": "INCOMPLETE",
"type": "INDIVIDUAL_VERIFY_ADDRESS",
"variant": {
"alias": "verify_address",
"id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
"name": null
}
}
}
],
"customer_ref": null,
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}

In the following example, an application needs to be approved or rejected manually, which we can see because the action_type is REVIEW_APPLICATION.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "MANUAL_ACTION_REQUIRED",
"secret": "yourSecret",
"timestamp": 1569499655,
"data": {
"actions": [
{
"action_type": "REVIEW_APPLICATION",
"application": {
"id": "edc23993-eb6a-9d89-bb79-5b8925b33224",
"product": {
"alias": "forexo_basic",
"id": "b0ce7c17-2cab-86e7-9a83-ebee0d4d5dc8",
"name": "Forexo Basic Account"
},
"status": "APPLIED"
},
"due": "NOW"
}
],
"customer_ref": null,
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}

In this last example, an application has been decided and no manual actions are left. We know there are no manual actions on this application because the actions array is empty.

Sample callback:

{
"id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
"event": "MANUAL_ACTION_REQUIRED",
"secret": "yourSecret",
"timestamp": 1569499659,
"data": {
"actions": [ ],
"customer_ref": null,
"profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
}
}

For an example of when you may want to use this webhook event, see Handing the APPLIED and IN_REVIEW status.

Customer request changed

A user has sent a document request to an applicant or an applicant has completed a document request.

This webhook is only for the Collect service. Contact us to learn more.

The Profile status changed, Task is complete changed, and Collection steps completed webhooks are deprecated.

How to configure webhooks

To enable a webhook to send callbacks:

  1. Go to Manage account > Webhook config.
  2. Select Webhooks enabled.
  3. Add your Secret to the Shared secret field. Ensure that your integration checks the Secret when webhook callbacks are received. This will make sure a malicious third party can't intercept the callback and provide you with false information.
  4. Add the endpoint you want to receive callbacks to the Endpoint field.
  5. Select the webhook events you want to listen to from Enabled events. You can select as many as you like.
  6. Click Save.

Receiving webhooks

Whitelisting the webhook IP address

All webhook callbacks are sent from the same IP address: 35.195.138.186.

If you're blacklisting other IP addresses, you should add this IP address to your whitelist to ensure you can receive webhooks.

Authenticating the request

When you receive a callback, you should ensure the secret in the callback matches the secret you added when you configured your webhooks.

The shared secret is sent in two places in the callback:

  • As a parameter in the webhook response.
  • As an HTTP Authorisation header with the bearer type.

Returning a 200 response

The webhooks have guaranteed ordering, and we'll retry delivering webhook callbacks until we receive a 200 response from you.

When you receive a webhook callback, you should return a 200 response to prevent the callback from being sent again.

The webhook status queue

The webhook status queue indicates whether your webhook events are sending as expected.

  • Queue: Whether the queue of callbacks is Empty (and therefore the webhooks are working as expected), waiting to send a specific number of callbacks, or Stalled (meaning that callbacks are not being sent).
  • Last processed: How long it's been since the last webhook callback was sent.
  • Recent failures: If any callbacks are waiting to send, this list displays the 10 most recent callbacks that are waiting.

Click Refresh to clear any Recent Failures from the list.

If the webhook status queue is stalled, you can resolve it by following these steps.


How did we do?


Powered by HelpDocs