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"
  }
}

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"}
  }
}

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
balance.low_balance
Balance fell below configured threshold
balance.depleted
Account balance reached zero
order.delivery_complete
All recipients in an order successfully delivered
order.delivery_partial
Some (but not all) recipients delivered
order.bounced
Recipient delivery bounced (invalid email, mailbox full, etc.)
order.canceled
Scheduled order canceled
recipient.redeemed
Recipient redeemed their reward
campaign.triggered
Campaign rule triggered an automatic order