Sign in
API Reference

Webhook Events

Webhook events are delivered to your registered endpoint as HTTP POST requests. Configure webhooks in the Developer Portal. See the Webhooks Guide for setup instructions and signature verification.

Envelope format

All webhook deliveries share a common envelope. The data field varies by event type.

Field
Type
Description
eventId
string
Unique event identifier (UUID). Use for idempotent processing.
eventType
string
Event type string (see table below).
createdAt
string
ISO 8601 timestamp.
data
object
Event-specific payload.

HTTP headers

Header
Description
Content-Type
application/json
X-Giftronaut-Signature
HMAC-SHA256 signature: sha256={hex}
User-Agent
GiftronautAPI-Webhook/1.0

Balance events

balance.ach_approved

Triggered when an ACH top-up request is approved and funds are added to the account.

{
  "eventType": "balance.ach_approved",
  "data": {
    "organizationId": "ORG-001",
    "amount": 5000.00,
    "currency": "USD",
    "approvedBy": "admin@giftronaut.com"
  }
}

balance.ach_rejected

Triggered when an ACH top-up request is rejected.

{
  "eventType": "balance.ach_rejected",
  "data": {
    "organizationId": "ORG-001",
    "amount": 5000.00,
    "currency": "USD",
    "reason": "Insufficient documentation"
  }
}

balance.low_balance

Triggered when account balance falls below the configured threshold.

Configurable: Set the threshold amount (USD) in the webhook subscription settings. 
{
  "eventType": "balance.low_balance",
  "data": {
    "organizationId": "ORG-001",
    "currentBalance": 42.50,
    "threshold": 100.00,
    "currency": "USD"
  }
}

balance.depleted

Triggered when account balance reaches zero.

{
  "eventType": "balance.depleted",
  "data": {
    "organizationId": "ORG-001",
    "currency": "USD"
  }
}

Order events

order.created

Triggered when a reward link order is created and ready for processing. Particularly useful for tracking asynchronous reward link order completion.

{
  "eventType": "order.created",
  "data": {
    "orderId": "OT20260415001234",
    "orderType": "LINK",
    "cardType": "BRANDED_CARD",
    "quantity": 10,
    "totalCost": {"amount": 500.00, "currency": "USD"}
  }
}

order.delivery_complete

Triggered when all recipients in an order have been successfully delivered.

{
  "eventType": "order.delivery_complete",
  "data": {
    "orderId": "OT20260415001234",
    "orderType": "ONE_TIME",
    "cardType": "BRANDED_CARD",
    "recipientCount": 10,
    "sentCount": 10
  }
}

order.delivery_partial

Triggered when some (but not all) recipients have been delivered. Useful for monitoring large batch orders.

{
  "eventType": "order.delivery_partial",
  "data": {
    "orderId": "OT20260415001234",
    "recipientCount": 100,
    "sentCount": 75,
    "bouncedCount": 2
  }
}

order.bounced

Triggered when a recipient delivery bounces (invalid email, mailbox full, etc.).

{
  "eventType": "order.bounced",
  "data": {
    "orderId": "OT20260415001234",
    "recipientEmail": "invalid@example.com",
    "reason": "MAILBOX_NOT_FOUND"
  }
}

order.canceled

Triggered when a scheduled order is canceled.

{
  "eventType": "order.canceled",
  "data": {
    "orderId": "OT20260415001234",
    "orderType": "ONE_TIME",
    "canceledAt": "2026-04-15T14:30:00Z"
  }
}

Test event

test.ping

Sent when you click Send Test in the webhook dashboard. Use this to verify your endpoint is receiving and processing webhooks correctly. 

{
  "eventType": "test.ping",
  "data": {
    "message": "This is a test webhook from Giftronaut API.",
    "endpointId": 42
  }
}

Coming soon

The following events are planned for future releases:

Event Type
Description
recipient.redeemed
Recipient redeemed their reward
campaign.triggered
Campaign rule triggered an automatic order