Skip to main content

​
Number of HTTP calls sent

Your endpoint may receive several HTTP calls for the same event, depending on the event. When a transaction reaches a final status such as failed or successful, the related webhook is normally sent once. For intermediate statuses such as pending or action_required, the webhook may be sent more than once. This happens when the provider data changes: the HUB2 API received an update from the provider, but not one that determines the final status of the transaction. A delivery that is retried (see below) also reaches your endpoint more than once. Every attempt for the same event carries the same event id, which you can use to ignore duplicates. A status can also be notified again as a new event with a new id, for example when HUB2 support re-sends a webhook. Make your processing idempotent on the object (data.id) and its status, not only on the event id.

​
In case of HTTP failure

If the target URL cannot be reached for any reason (network failure, server unavailable, etc.), the HTTP call fails. To handle this, the HUB2 API retries failed deliveries. This is the default behaviour. With the no_retry strategy set in the dashboard, a failed delivery is not retried and the webhook is not disabled.

​
Retry strategy

After a failed delivery, the webhook is sent again after an initial delay of 60 seconds. Each new failure extends this delay exponentially, following this formula:
This gives the following delays before each retry:
  1. 1 minute
  2. 3 minutes
  3. 7 minutes
  4. 15 minutes
  5. 31 minutes
  6. 63 minutes
  7. 127 minutes
  8. and so on, doubling each time.
Retries do not last forever. If the delivery still fails after 10 retries (11 attempts in total, about 34 hours after the first one), the HUB2 API considers the target URL unreachable, stops retrying and automatically disables the webhook.

​
Timeout

If the target URL takes longer than 5 seconds to respond, the HUB2 API stops waiting and counts the call as a failure.
A timeout triggers the retry strategy, so a slow endpoint is a common reason for receiving the same webhook several times.

​
Automatic deactivation

A disabled webhook stays disabled until you enable it again. Events that occur while it is disabled are not delivered, so make sure this never happens. Deliveries still pending or being retried when the webhook is disabled are dropped as well. After re-enabling it, retrieve the status of the affected transactions through the API. You can enable the webhook again at any time by setting its status back to enabled through the API.
Update a webhook
To prevent deactivation, the endpoint receiving the webhook must always return a 2xx HTTP status code. Any other response, or no response at all, counts as a failure. Once the retries are exhausted, the webhook is disabled automatically.