Overview

Webhooks are a method for your application to receive real-time notifications about activities within our system. They offer an efficient way to stay updated on all actions without the need for constant polling or syncing, which can save resources and reduce the potential for errors.

In cases where you’re synchronizing with a CRM or another external system, subscribing to webhooks is the best practice. This approach ensures that you receive immediate updates about the status of your requests, streamlining your integration process.

Currently, we do not provide webhook management endpoints. All events for all resource transitions are triggered automatically. In the future, partners will be able to subscribe to and manage webhook events based on their specific needs.

Events overview

Whenever important changes occur in our resources, they are recorded as events. Each event includes data about affected resources and details such as the timing of the change. For example, if a product is depleted or reached a determined balance threshold, an event like balance.threshold.exceeded is recorded.

Event object

Each event object contains key details about the change that occurred. The typical structure of an event includes:

• id: the unique identifier of the event
• type: The event type (e.g., product.depleted)
• created_at: the timestamp of when the event occurred
• data: the actual event data associated with the event, ussualy a snapshot of the resource that changed

Handling the Event Object

• Use the id field to track events and prevent duplicate processing.
• Rely on the type field to determine the appropriate handling logic.
• Extract relevant data from the data field to update your system.

Event types

Our webhook system triggers events for various resource transitions. Below are some common event categories and their corresponding types:

Event Type	When it Occurs
balance.threshold.exceeded	When the balance falls below a threshold.
product.depleted	When a product is no longer available.
product.terminated	When a product is terminated.
product.active	When a product becomes active.
product.canceled	When a product is canceled.
product.throttling.applied	When throttling is applied.
subscription.active	When a subscription is activated.
subscription.grace	When a subscription enters a grace period.
subscription.suspended	When a subscription is suspended.
subscription.terminated	When a subscription is terminated.
subscription.deactivated	When a subscription is deactivated.
subscription.canceled	When a subscription is canceled.
subscription.sim_profile.installed	When a SIM profile is installed.
subscription.sim_profile.deleted	When a SIM profile is deleted.
subscription.sim_profile.ready_for_installation	When a SIM profile is ready for installation.
order.completed	When an order is successfully processed.
order.failed	When an order fails to process.
porting.draft	MNP-OUT: process reaches 1GLOBAL MNP-IN process is accepted by the regulator
porting.pending	When porting is in pending
porting.scheduled	When porting is scheduled for a specific time.
porting.processing	When porting is being processed.
porting.completed	When porting is successfully completed.
porting.cancelation_requested	When porting cancellation is requested.
porting.canceled	When porting is canceled.
porting.rejected	When porting is rejected.
invoice.open	When a new invoice is open.

Retries & Duplicate Handling

Retry Policy

Whenever a webhook request fails (i.e., returns a non-2XX status code such as a 4XX or 5XX error), we will retry the request up to four times with the following intervals:

Retry Attempt	Interval
1st retry	3 seconds
2nd retry	5 seconds
3rd retry	10 seconds
4th retry	20 seconds

If all retry attempts fail, we will stop retrying and disable the webhook.

We can customize the retry policy based on different configurations, such as the number of retry attempts and intervals.

Handling Duplicate Events

Since webhooks are retried, your system must be idempotent to prevent duplicate processing. Recommended approaches:

• Use the id field to track processed events and avoid reprocessing the same event multiple times.
• Store event IDs in a database or cache to check if an event has already been handled.
• Check for duplicates before processing Before processing a new event, check if its unique identifier already exists in your storage. If it does, this indicates that the event has already been processed, so you can safely skip it.

Out of order delivery

Webhooks are not guaranteed to arrive in the exact sequence they were triggered. Events may be delayed or delivered out of order due to network conditions.

Strategies for Handling Out-of-Order Events

• Use timestamps: Rely on the timestamp field to determine the actual sequence of events.
• Track the latest state: Maintain the current state of resources instead of assuming strict event ordering.

Securing your webhook URL

To ensure the security and authenticity of webhook deliveries, we offer several mechanisms to protect your webhook endpoint:

1. Basic Authentication

You can secure your webhook endpoint by requiring Basic Authentication. This method involves including a username and password in the HTTP request header to authenticate the request before it's processed.

• How it works:
  • Each webhook request will include the Authorization header with a base64-encoded string of your username and password.
  • Verify the credentials before processing the webhook to ensure that the request is coming from a trusted source.

2. Mutual TLS (mTLS)

For a higher level of security, you can use mutual TLS (mTLS), where both your server and our system authenticate each other using client and server certificates.

• How it works:
  • Both the client and the server exchange certificates during the handshake process.
  • The server authenticates the client by validating its certificate, and the client verifies the server's certificate.
  • This ensures that only trusted parties can communicate with your webhook endpoint.

3. IP Filtering

You can restrict webhook deliveries to specific IP ranges by enabling IP Filtering. This ensures that only requests coming from trusted IP addresses are allowed to reach your endpoint.

• How it works:
  • You define the IP ranges or addresses that are allowed to send requests to your webhook endpoint.
  • Requests originating from outside these trusted IP ranges will be rejected.
  • This adds an extra layer of protection by preventing unauthorized access based on the source IP address.