When you create a new webhook, it receives all matching events by default. If the endpoint contains an error or cannot handle the traffic volume, the issue can affect all users at once.

With the Rollout percentage setting, you can start with a small share of traffic, such as 10%, check that the endpoint works as expected, then increase the value to 50% and later to 100%.

The rollout keeps the sample stable as you increase the percentage. This means that entities that already receive events continue receiving them when you scale up.

You can use this setting for the following scenarios:

• Gradually rolling out a new or updated endpoint.
• Monitoring and alerting on a representative traffic sample.
• A/B testing event-processing logic across different endpoints.

How rollout percentage works

For each event, Sumsub calculates a value based on the entity and the webhook. Then we compare this value with the configured rollout percentage.

If the value falls within the configured percentage, the system sends the event to the webhook. Otherwise, we skip the event for that webhook.

Rollout percentage has the following properties:

• Deterministic and stable. The same entity always gets the same result for the same webhook. For example, if an applicant falls into the 30% sample, the webhook receives all events for this applicant every time. This prevents partial event histories for a single entity.
• Monotonic when increasing the percentage. When you increase the value, the system only adds new entities to the sample. Entities that already received events continue receiving them. This makes gradual rollouts, such as 10% → 50% → 100%, safe.
• Independent for each webhook. Sumsub calculates the sample separately for each webhook. Two webhooks with the same rollout percentage can receive different, partially overlapping subsets of events. Changing the percentage for one webhook does not affect other webhooks.

Sampling entity

Sumsub calculates the rollout percentage based on the event entity. The entity depends on the event type.

When an applicant exists for the event, the system uses the applicant as the sampling entity. If the event has no applicant, the system uses the event object instead.

The table below shows which entity Sumsub uses for rollout percentage sampling for each event category.

Backward compatibility

Existing webhooks created before the Rollout percentage field was introduced continue working as before. They behave as if the rollout percentage equals 100, so they receive all matching events.

📘

Note

If you do not specify the field, the system uses 100 as the default value.

Set rollout percentage

To configure rollout percentage:

1. In the Webhook manager section, open the webhook you want to configure.
2. In the Rollout percentage field, enter an integer from 0 to 100.
3. Save the changes.

The following values define how the webhook receives events: