Webhooks

Webhooks are a method for your application to receive real-time notifications about activities within Connect. They offer an efficient way to stay updated on lifecycle changes without constant polling or syncing, which saves resources and reduces the potential for errors.

When you synchronize 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 and streamlines your integration process.

Webhook delivery is configured by 1GLOBAL during onboarding. Once your endpoint is active, events for resource transitions are triggered automatically. You can verify your webhook configuration through the API, but you do not create webhook configurations yourself. In the future, partners will be able to subscribe to and manage webhook events based on their specific needs.

For setup, verification, and operational guidance, see Configure Webhooks.

Events overview

Whenever important changes occur in Connect 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 reaches a determined balance threshold, an event such as 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 (for example, product.depleted)
• created_at: the timestamp of when the event occurred
• data: the event data associated with the change, usually 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

Connect triggers webhook events for many resource transitions, including orders, subscriptions, products, portings, renewals, invoices, and phone numbers.

For the complete and authoritative list of event types and payload schemas, see Events in the API Explorer.

Retries and duplicate handling

Retry policy

When a webhook delivery fails (returns a non-2XX status code), Connect retries the delivery up to 18 times with an increasing delay between attempts, capped at 30 minutes once reached.

Backoff schedule:

The full retry cycle takes approximately 4h 20min. If all 18 attempts fail, the event is moved to a dead-letter queue (DLQ) and no further automatic delivery is attempted.

The retry policy follows the schedule above by default. Partners that require a different cadence (for example, more frequent attempts or a shorter total window) can request a tailored configuration through their onboarding contact.

Handling duplicate events

Because 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 whether an event has already been handled.
• Before processing a new event, check whether its unique identifier already exists in your storage. If it does, the event has already been processed and you can safely skip it.

For broader idempotency guidance on write operations, see Idempotency.

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 created_at 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, Connect supports several mechanisms to protect your webhook endpoint.

1. Basic authentication

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

How it works:

• Each webhook request includes the Authorization header with a base64-encoded username and password.
• Verify the credentials before processing the webhook to ensure that the request comes from a trusted source.

2. HMAC signature verification

Each webhook request is signed with a shared secret using HMAC-SHA-256. Your endpoint recomputes the signature and compares it against the value sent in the request headers to confirm authenticity and integrity.

Headers sent by Connect:

Signature format:

Each signature is v{version},{base64_signature}. During a key rotation window, Webhook-Signature contains two signatures separated by a space — one from the new key and one from the previous key:

v2,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= v1,hnO3f9T8Ytu9HwrXslvumlUpqtNVqkhqw/enGzPCXe5BdqzCInXqYXFymVJaA7AZdpXwVLPo3mNl8EM+m7TBAg==

Accept the request if any of the signatures matches.

String to sign:

{Webhook-ID}.{Webhook-Timestamp}.{raw_json_body}

The payload is already delivered as canonicalized and minimized JSON (RFC 8785). Use the raw body exactly as received — do not reformat, pretty-print, or re-serialize it before verifying.

Verification steps:

1. Read the raw request body as bytes. Do not parse it yet.
2. Read Webhook-ID, Webhook-Timestamp, and Webhook-Signature.
3. Reject the request if the timestamp is too old (recommended tolerance: 5 minutes).
4. Build the signature input string: {Webhook-ID}.{Webhook-Timestamp}.{raw_body}.
5. Decode your stored signing_secret from Base64 to raw bytes.
6. Compute expected = base64(HMAC_SHA256(secret_bytes, signature_input)).
7. Compare expected against each signature in Webhook-Signature (after stripping the v{n}, prefix) using a constant-time comparison. Accept if any matches; otherwise reject with 401.

Handling key rotation

The signing secret is rotated by calling POST /webhooks/{webhook-id}/rotate-signing-secret. The response includes:

• signing_secret — the new key, Base64-encoded
• signature_algorithm — the algorithm identifier (hmac-sha256)
• key_version — the integer version associated with the new key

For a short overlap window (1 hour) after a rotation, Connect signs requests with both the new key and the previous key, and delivers both signatures in Webhook-Signature. Your endpoint should:

• Keep the previous signing_secret alongside the new one during the overlap window.
• On each request, try each signature until one matches.
• Discard the previous secret once the overlap window has passed.

Because rotation always begins by creating a new key, you can perform an immediate revocation by rotating twice in a row.

3. Mutual TLS (mTLS)

For a higher level of security, you can use mutual TLS (mTLS), where both your server and Connect 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.

4. IP filtering

You can restrict webhook deliveries to specific IP ranges by enabling IP filtering. This ensures that only requests from trusted IP addresses can 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 are rejected.
• This adds an extra layer of protection by preventing unauthorized access based on the source IP address.