Webhooks

ArelHub uses two distinct webhook patterns. This guide explains both and how to build reliable handlers for each.

Pattern 1 — Inbound provider callbacks

Endpoints hosted by ArelHub that receive event notifications from carriers and payment processors. You do not call these endpoints. ArelHub registers them with each provider.

Authentication is via HMAC-SHA256 payload signature verification, not JWT or API key.

Retrieve carrier events for a dispatched message:

      
        GET /v1/messages/{id}/carrier-events
        Authorization: Bearer eyJ...
      
    

Pattern 2 — Customer webhook subscriptions

Configure ArelHub to push events to a URL you control.

      
        GET  /v1/billing/webhooks/config
        POST /v1/billing/webhooks/enable
        POST /v1/billing/webhooks/disable
        POST /v1/billing/webhooks/regenerate-secret
      
    

After rotating the signing secret, update your handler immediately to avoid rejected deliveries.

Validating signatures

All webhooks delivered to your endpoint are signed using HMAC-SHA256. Validate the signature before processing any payload.

        
          // C# — timing-safe comparison
          static bool IsValidSignature(string payload, string secret, string headerSig)
          {
            using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
            byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
            string computed = Convert.ToHexString(hash).ToLowerInvariant();
            return CryptographicOperations.FixedTimeEquals(
                Encoding.UTF8.GetBytes(computed),
                Encoding.UTF8.GetBytes(headerSig));
          }
        
      

Use a timing-safe comparison (not == or string.Equals) to prevent signature oracle attacks.

Idempotency

Webhooks may be delivered more than once. Design your handler to be idempotent:

• Store the event ID on first receipt and skip duplicate deliveries.
• Return 200 OK immediately, then process asynchronously.
• Confirm signature before any side-effects.

Reliability checklist

• Signature validation runs before payload processing
• Handlers return 200 quickly and process asynchronously where needed
• Event IDs are deduplicated
• Signing secrets are stored in environment variables, not source code
• Secrets are rotated immediately on suspected compromise

← Messaging  ·  Errors & Limits →