Webhooks

For what this feature does, see Webhooks in Platform. This item appears in the Control Center provider sidebar only when the webhooks provider feature is active.

View webhooks

Permissions: manage_webhooks

If the provider feature is activated, in the dropdown menu of the provider select the option Manage Webhooks. In this view, webhooks are listed in a table containing the following information.

ColumnDescription
IDWebhook identifier
Webhook URLReceiving URL for ioki POST requests, for example:
https://your.domain.com/webhooks/processing.json
Subscribed eventsIf Subscribe to all events = Subscribe to all events, shows All events.

If Subscribe to all events = Subscribe only to specific events, shows the number of events or, if only one is selected, the event name, for example ride.created.
Product filterIf Product filter = Disable product filter, shows (off).

If Product filter = Enable product filter, shows the number of products or, if only one is selected, the product name.
Deliver webhook eventWhether webhook delivery is enabled (True/False)
Circuit breakerWhether the circuit breaker is closed or open
DeliveryWhether webhook delivery is currently possible. This is True only when Deliver webhook event is True and Circuit breaker is Closed

Create a webhook

Permissions: manage_webhooks

To create a webhook, select Create new and enter the following information.

  • API Version. Select 20201201S or 20201201 from the dropdown menu. This mainly defines the format in which ioki Platform serializes data that is then sent to the webhook URL. The “S” stands for slim serializer. Then select Next.

Definition

  • Webhook URL. Enter a URL. This is the receiving end that ioki sends its POST requests to.

ioki Platform only supports https.

  • Secret. Enter a secret. This is a pre-shared key used to calculate a message authentication code that enables the receiving end to authenticate the sender and ensure the integrity of the transmitted data. The secret must be shared via a secure channel and should have a sufficient length and non-trivial alphabet. We recommend at least 24 characters obtained via a secure token generator, with at least lower case characters, upper case characters and digits. Secure random UUIDs are also a valid option.
  • SLA Group (optional): Enter the SLA group. This is a text value, which defaults to blank if not provided. The SLA group is not exposed via the Platform API or any other API. Its primary purpose is for internal use, such as health endpoint monitoring and integration with services like UptimeRobot.

Delivery

Deliver webhook event: Activate if webhook events should be delivered for the given webhook.

Circuit breaker settings

In the event of a provider’s internet outage, webhooks are collected and queued until connectivity is restored. However, this accumulation may lead to undesirable consequences upon reconnection, as all queued webhooks are fired in quick succession. To address this issue, we implemented a circuit breaker. For each webhook, the sensitivity of the circuit breaker can be adjusted to configure under what conditions the breaker is triggered. Should the fuse pop out, indicating a prolonged server offline scenario, webhook delivery can be disabled.

  • Failure ratio threshold (default = 0.2): Define a failure ratio threshold.

  • Max failures (default = 100): Enter the number of max failures.

  • Timeframe (default = 300): Enter a timeframe (in seconds).

  • Mode. Select one of the following options from the dropdown menu:

    • Max failures AND Failure ratio exceeded. The webhook is short circuited if both the max failures and the failure ratio are exceeded.
    • Max failures OR Failure ratio exceeded. The webhook is short circuited if either the max failures or the failure ratio are exceeded.
    • Max failures exceeded. The webhook is short circuited if the max failures are exceeded.
    • Failure ratio exceeded. The webhook is short circuited if the failure ratio is exceeded.

Product filter

  • Product filter. Select Disable product filter or Enable product filter from the dropdown menu. In case the product filter is enabled, only webhooks that relate to one of the selected products are delivered. Note that webhooks that do not belong to a specific product are no longer sent if the filter is enabled.

  • Deliver webhook events only for those products. Select which products webhook events should be delivered.

Event type filter

  • Subscribe to all events. Select Subscribe to all events or Subscribe only to specific events from the dropdown menu. Subscribe to all events activates all possible webhook events. If Subscribe only to specific events is selected, then select the specific events from the list.

Open the detailed view of a webhook

Permissions: manage_webhooks

To open the detailed view of a webhook, select ⚙️ > Show in the dropdown menu. Alternatively, select its webhook URL in the table.

Edit a webhook

Permissions: manage_webhooks

To edit a webhook, select ⚙️ > Edit in the dropdown menu. Make the desired changes and then select Save.

Close/open circuit breaker

Permissions: manage_webhooks

To close or open the circuit breaker, select ⚙️ > Close circuit breaker or Open circuit breaker in the dropdown menu. A closed circuit breaker allows the flow of webhooks. Alternatively, this can be toggled by clicking the switch icon in the Circuit breaker column.

Enable/disable delivery

Permissions: manage_webhooks

To enable or disable delivery, select ⚙️ > Enable delivery or Disable delivery in the dropdown menu. Alternatively, this can be toggled by clicking the switch icon in the Deliver webhook event column.

Delete a webhook

Permissions: manage_webhooks

To delete a webhook, select ⚙️ > Delete in the dropdown menu and then OK.