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 these events:

  • Product status changed: The status of a product application has changed (e.g. an application has gone from Approved to In review). For an example of when you may want to use this, see Tracking the status.
  • Check completed: The results of a check are returned. If an error occurs when a check is run, this is returned as well. For an example of when you may want to use this, see Getting check results.
  • Product badge changed: The application processing state (also known as the "flag") has changed. For an example of when you may want to use this, see Displaying the application processing state.
  • Risk level changed: The application risk level has changed. Note that this webhook event is only applicable if you're using the Risk module. 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.
  • Collected data updated: A profile's collected data has changed in PassFort. 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: The state of a custom form has changed (e.g. it was created, submitted, or approved).
  • Manual action required: A profile's application requires manual action to progress to the next status. For an example of when you may want to use this, 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. Note that this webhook is only for the Collect service. Contact us to learn more.

To learn how to enable webhook events, see How to configure webhooks.

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:

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