Webhooks

Overview

Webhooks let your application subscribe to specific events (e.g. order delivery completed, balance low) and receive an HTTP POST to your endpoint whenever that event occurs. This eliminates the need for polling and enables real-time integrations.

Setting up a webhook

1. Register your endpoint

Go to Webhooks in the portal sidebar, select a credential, and enter your HTTPS endpoint URL. The URL must be publicly accessible and use HTTPS.

2. Challenge verification

When you register an endpoint, Giftronaut sends a POST request to your URL with a JSON body containing a challengeToken. Your server must respond with the same token to prove ownership.

// Giftronaut sends:
POST https://your-server.com/webhooks/giftronaut
Content-Type: application/json

{"challengeToken": "a1b2c3d4e5f6..."}

// Your server should respond with:
HTTP 200 OK
Content-Type: application/json

{"challengeToken": "a1b2c3d4e5f6..."}

If your server responds correctly, the endpoint is automatically activated. Otherwise, you can manually enter the token in the portal.

3. Subscribe to events

Once verified, use the toggle switches to subscribe to the events you want to receive. You can enable or disable events at any time.

Webhook payload

Every webhook delivery is a POST request with a JSON body following this envelope format:

{
  "eventId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "eventType": "order.delivery_complete",
  "createdAt": "2026-04-15T14:30:00.000",
  "data": {
    "orderId": "OT20260415001234",
    "cardType": "BRANDED_CARD",
    "recipientCount": 10,
    "sentCount": 10
  }
}

Verifying signatures

Every webhook request includes an X-Giftronaut-Signature header containing an HMAC-SHA256 signature of the request body, computed with your signing secret. Always verify this signature to ensure the request is authentic.

Verification algorithm

// 1. Extract the signature from the header
String signature = request.getHeader("X-Giftronaut-Signature");
// e.g. "sha256=5d41402abc4b2a76b9719d911017c592..."

// 2. Compute the expected signature
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(
    signingSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] hash = mac.doFinal(requestBody.getBytes(StandardCharsets.UTF_8));
String expected = "sha256=" + HexFormat.of().formatHex(hash);

// 3. Compare using constant-time comparison
if (!MessageDigest.isEqual(
    expected.getBytes(), signature.getBytes())) {
    return ResponseEntity.status(401).build();
}

Node.js example

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(body, 'utf8')
      .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature));
}

Python example

import hmac, hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Responding to webhooks

Your endpoint must respond within 5 seconds with a 2xx status code. Any non-2xx response or timeout is treated as a failure.

• Return 200 OK or 204 No Content to acknowledge receipt.
• Process the event asynchronously if it takes longer than a few seconds.
• Use the eventId field for idempotent processing in case of retries.

Retry policy

Failed deliveries are retried up to 5 times with exponential backoff:

After 5 failed attempts, the delivery is marked as failed. You can monitor delivery status in the Delivery History section of the webhook dashboard.

Best practices

• Always verify signatures before processing any webhook payload.
• Respond quickly (under 5 seconds). Offload heavy processing to a queue.
• Implement idempotency using eventId to handle duplicate deliveries.
• Use HTTPS with a valid TLS certificate on your endpoint.
• Monitor delivery history in the dashboard to catch failures early.
• Test with the Send Test button in the dashboard before going live.