Configure Webhooks

Webhook configuration for Connect is currently handled internally by 1GLOBAL during onboarding. Your application does not create the webhook configuration itself: you provide the delivery details, and then use the API to verify which webhook configuration is active for your tenant and which event schemas your endpoint should accept.

Tip: Treat webhooks as the source of truth for asynchronous lifecycle updates such as provisioning completion, failures, SIM installation readiness, renewals, and status changes.

Endpoint requirements

Regardless of the authentication method you pick, your endpoint must:

be reachable over HTTPS
accept POST requests with application/hal+json payloads
return a 2XX response only after the event has been accepted for processing

For reliability guidance, see Go to Production.

Choose an authentication method

Connect supports three mechanisms to secure webhook deliveries. Pick the one that best fits your infrastructure. IP filtering can be layered on top of any of them.

Option 1 — HMAC signature verification (recommended)

Connect signs each request with a per-webhook secret using HMAC-SHA-256. Your endpoint recomputes the signature and compares it against the header. Best default for most integrations.

Provide to 1GLOBAL:

Endpoint URL (HTTPS)

1GLOBAL provides you:

The signing secret, retrievable and rotatable via POST /webhooks/{webhook-id}/rotate-signing-secret. The response includes signing_secret (Base64-encoded), signature_algorithm, and key_version.

Your endpoint must:

Read the raw request body (do not parse it before verifying).
Recompute HMAC_SHA256(base64_decode(signing_secret), "{Webhook-ID}.{Webhook-Timestamp}.{raw_body}").
Base64-encode the result and compare against each signature in the Webhook-Signature header.
Reject requests whose signature does not match, and reject stale requests to prevent replay attacks (recommended tolerance: 5 minutes).

For the exact verification steps, header format, rotation window, and a code example, see Webhooks reference — HMAC signature verification.

Option 2 — Basic authentication

Simplest option to set up. Suitable when your endpoint already sits behind infrastructure that terminates TLS and restricts inbound access.

Provide to 1GLOBAL:

Endpoint URL (HTTPS)
Basic auth username
Basic auth password

Your endpoint must:

Reject any request without a valid Authorization: Basic <base64> header.

See Webhooks reference — Basic authentication.

Option 3 — Mutual TLS (mTLS)

Highest level of security. Both parties present certificates during the TLS handshake.

Provide to 1GLOBAL:

Endpoint URL (HTTPS)
Your server's public certificate or the CA chain used to sign it

1GLOBAL provides you:

The client certificate (or CA chain) it will present when calling your endpoint

Your endpoint must:

Terminate TLS with client certificate verification enabled.
Validate that the presented client certificate is one issued by the agreed CA.

See Webhooks reference — Mutual TLS (mTLS).

Optional — IP filtering

Can be layered on top of any of the above. Restrict inbound traffic to the IP ranges Connect will call from. Request the current Connect egress IPs from your onboarding contact.

See Webhooks reference — IP filtering.

Verify your webhook configuration

Once 1GLOBAL has configured your tenant, you can inspect the active webhook setup through the Webhooks API:

List webhooks: returns the webhook configurations available for the authenticated tenant
Retrieve webhook: returns the details for a specific webhook configuration

From these endpoints you can confirm values such as:

url
enabled_events
api_version
signature_algorithm

Review the event payloads your endpoint must handle

The webhook delivery itself is documented under the Events API. These entries show the exact payload schema sent to your endpoint for each event type.

Start here:

Depending on your integration journey, you may also need to handle additional event families such as subscription, product, phone number, porting, and renewal events. The Events section is the authoritative place to review those payloads.

Connect events back to API resources

When a webhook arrives, use the identifiers in the payload to reconcile state in your system and, when needed, retrieve the latest resource state from the API.

Common follow-up endpoints:

This pattern is especially useful when:

an activation is still progressing asynchronously
an order fails and you need the latest order status
a SIM profile becomes ready for installation
you need to confirm the final subscription or product state after a lifecycle event

Recommended partner behavior

Keep your webhook handler idempotent
Store processed event IDs to prevent duplicate handling
Do not assume events arrive in order
Link incoming events to your internal order, subscription, product, or customer records

For a concrete lifecycle example, see Activate with a new number, which shows how webhook events fit into the activation journey.

On this page