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

order.delivery_complete

Triggered when all recipients in an order are successfully delivered.

{
  "eventType": "order.delivery_complete",
  "data": {
    "orderId": "OT12345678",
    "cardType": "BRANDED_CARD",
    "recipientCount": 10,
    "sandbox": false,
    "occurredAt": "2026-07-23T09:00:00Z"
  }
}

order.delivery_partial

Triggered when some (but not all) recipients in an order are delivered.

{
  "eventType": "order.delivery_partial",
  "data": {
    "orderId": "OT12345678",
    "cardType": "BRANDED_CARD",
    "recipientCount": 10,
    "deliveredCount": 7,
    "bouncedCount": 3,
    "sandbox": false,
    "occurredAt": "2026-07-23T09:00:00Z"
  }
}

order.bounced

Bounced delivery events are aggregated and sent in batches every 5 minutes. Because of this batching, an order.bounced event might arrive after the order.delivery_complete event for the same order. Do not rely on the delivery order of these events. 

{
  "eventType": "order.bounced",
  "data": {
    "orderId": "OT12345678",
    "cardType": "BRANDED_CARD",
    "from": "2026-07-23T08:55:00Z",
    "to": "2026-07-23T09:00:00Z",
    "items": [
      {
        "orderId": "OT12345678",
        "recipientEmail": "alice@example.com"
      },
      {
        "orderId": "OT12345678",
        "recipientEmail": "bob@example.com"
      }
    ],
    "sandbox": false,
    "occurredAt": "2026-07-23T09:00:00Z"
  }
}

order.canceled

Triggered when a scheduled order is canceled.

{
  "eventType": "order.canceled",
  "data": {
    "orderId": "OT12345678",
    "cardType": "BRANDED_CARD",
    "sandbox": false,
    "occurredAt": "2026-07-23T09:00:00Z"
  }
}

Resend behavior

When you resend an order, the delivery lifecycle webhooks (order.delivery_complete, order.delivery_partial, and order.bounced) can fire again as the resent recipients are re-processed. Terminal events can therefore be delivered more than once. You should always deduplicate these events using the eventId field.

For example, if you resend an order that previously triggered order.delivery_complete with eventId: "uuid-1", the re-delivery will trigger a new order.delivery_complete event with a different eventId: "uuid-2".

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
recipient.redeemed
Recipient redeemed their reward
campaign.triggered
Campaign rule triggered an automatic order