Skip to main content

Using Passfort

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 payloads for different events.

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

Full Passfort product

When you're using the full Passfort product, you can enable webhooks for the following events

  • Product status changed

  • Task created

  • Check completed

  • Product badge changed

  • Risk level changed

  • Risk score changed

  • Task state changed

  • Collected data updated

  • Collected data changed

  • Form state changed

  • Manual action required

  • Customer request changed

  • Events created

  • Events updated

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

Customers joining Passfort will automatically use the Collected data changed webhook instead of the Collected data updated webhook. For descriptions and examples of the webhook payloads, see Webhooks in the API reference for the full Passfort

How to configure webhooks

To enable a webhook to send payloads:

  1. Go to Manage account > Webhook config.

  2. Select Webhooks enabled.

  3. If you would like webhooks to be sent in batches, select Enable batching. We recommend enabling batching.

  4. Add your Secret to the Shared secret field. Ensure that your integration checks the Secret when webhook payloads are received. This will make sure a malicious third party can't intercept the payload and provide you with false information.

  5. Add the endpoint you want to receive payloads to the Endpoint field.

  6. Select the webhook events you want to listen to from Enabled events. You can select as many as you like.

  7. Select Save.

Webhooks cannot be sent directly to a Salesforce endpoint because Salesforce interprets our Authorization header as an attempt to authorize requests in Salesforce. Any requests directly to a Salesforce endpoint will be rejected with a 401 Unauthorized Error. To work around this, send requests through an intermediary or use a webhook-altering tool like Webhook Relay.

Batching

When batching is enabled, multiple webhooks are delivered in a single request.

Webhook messages are added to a queue, and Passfort delivers the first 100 messages in the queue approximately every 0-10 seconds.

We recommend enabling batching - particularly for high-volume customers - because it's the fastest option. Without batching, webhooks are sent one at a time, in the order they were triggered.

Receiving webhooks

Allow listing the webhook IP address

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

The only exception is for customers in the UAE. These webhook payloads come from: 20.74.0.0/16 and 20.203.0.0/16.

If you're block-listing other IP addresses, you should add this IP address to your allow list to ensure you can receive webhooks.

Authenticating the request

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

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

  • As a parameter in the webhook response.

  • As an HTTP Authorization header with the bearer type.

Returning a 200 response

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

If you have batching disabled and a webhook cannot be sent, the webhook is retried using the following exponential backoff parameters while any other waiting webhooks are queued behind it:

  1. For the first 12 attempts, the webhook is retried after 30 seconds * power(2, attempts -1)

  2. After this, the webhook is retried daily.

When batching is enabled, a single request is sent containing multiple webhooks in an array. These are the first 100 webhooks in your queue. Once we receive a 200 response from you, we will remove these webhooks from your queue. If we do not receive a 200 response, those webhooks will remain in your queue and will be included in the next batch request. The batch request is retried using the same exponential backoff parameters described here.

To prevent a backlog, we recommend that your webhook receiver returns the 200 response immediately and that you add the webhook payloads to a queue managed by a separate process. To avoid processing webhooks twice, your queue should remember the last webhook ID that was processed and ignore any webhooks sent before that.

If your webhook receiver takes too long to send a 200 response, the webhook or queue will time out. When batching is enabled, your 200 response should be sent in 5 seconds or less. When batching is disabled, your response should be sent in 10 seconds or less.

The webhook status queue

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

  • Queue: Whether the queue of payloads is Empty, and therefore the webhooks are working as expected, waiting to send a specific number of payloads, or Stalled, meaning that payloads are not being sent.

  • Last processed: How long it has been since the last webhook payload was sent.

  • Recent failures: If any payloads are waiting to send, this list displays the 10 most recent payloads that are waiting.

Webhook status showing an empty queue.

Select Refresh to clear any Recent Failures from the list.

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

We do not advise disabling, then re-enabling the Webhooks enabled checkbox when you're troubleshooting because this may result in a loss of webhooks. Instead, use the Retry button to force the system to retry webhooks immediately and ignore any exponential backoff that might be in place.