Events & API Reference
Complete reference for all webhook event types, payload schemas, and HTTP specifications.
Event Overview
| Event Type | Category | Description |
|---|---|---|
checkout.completed | Payments | Checkout session completed successfully |
payment.completed | Payments | Payment succeeded (initial or recurring) |
payment.failed | Payments | Payment failed (card declined, etc.) |
subscription.created | Subscriptions | New subscription created |
subscription.renewed | Subscriptions | Recurring payment succeeded |
subscription.canceled | Subscriptions | Subscription canceled |
subscription.paused | Subscriptions | Subscription paused |
subscription.resumed | Subscriptions | Paused subscription reactivated |
subscription.past_due | Subscriptions | Payment overdue on subscription |
customer.created | Customers | New customer registered |
Common Payload Fields
All events share this base structure:
{
"id": "evt_uuid-v4",
"type": "event.type",
"created_at": "2026-02-16T14:30:00.000Z",
"data": { ... }
}
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique event identifier. Use this for idempotency checks. |
type | string | The event type (e.g., payment.completed) |
created_at | string (ISO 8601) | When the event was created |
data | object | Event-specific payload data (see below) |
Common data fields
Most payment-related events include these fields in the data object:
| Field | Type | Description |
|---|---|---|
data.customer.email | string | Customer email address |
data.customer.name | string | Customer full name (if collected) |
data.customer.stripe_customer_id | string | Stripe customer ID |
data.amount | number | Gross amount charged |
data.net_amount | number | Amount after platform fee deduction |
data.platform_fee | number | Platform fee amount |
data.currency | string | 3-letter ISO currency code (e.g., usd) |
checkout.completed
Fired when a customer successfully completes a checkout session.
{
"id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000001",
"type": "checkout.completed",
"created_at": "2026-02-16T14:30:00.000Z",
"data": {
"customer": {
"email": "john@example.com",
"name": "John Doe",
"stripe_customer_id": "cus_abc123"
},
"amount": 49.99,
"net_amount": 48.49,
"platform_fee": 1.50,
"currency": "usd",
"checkout_session_id": "cs_abc123",
"subscription_id": "sub_xyz789",
"mode": "subscription"
}
}
| Field | Type | Description |
|---|---|---|
checkout_session_id | string | Stripe Checkout Session ID |
subscription_id | string | null | Stripe Subscription ID (null for one-time) |
mode | string | "subscription" or "payment" |
payment.completed
Fired when a payment is successfully processed (both initial and recurring).
{
"id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000002",
"type": "payment.completed",
"created_at": "2026-02-16T14:30:00.000Z",
"data": {
"customer": {
"email": "john@example.com",
"name": "John Doe",
"stripe_customer_id": "cus_abc123"
},
"amount": 49.99,
"net_amount": 48.49,
"platform_fee": 1.50,
"currency": "usd",
"subscription_id": "sub_xyz789",
"invoice_id": "in_abc123",
"mode": "subscription"
}
}
payment.failed
Fired when a payment attempt fails (card declined, insufficient funds, etc.).
{
"id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000003",
"type": "payment.failed",
"created_at": "2026-02-16T14:30:00.000Z",
"data": {
"customer": {
"email": "john@example.com",
"name": "John Doe",
"stripe_customer_id": "cus_abc123"
},
"amount": 49.99,
"currency": "usd",
"subscription_id": "sub_xyz789",
"invoice_id": "in_abc123"
}
}
Subscription Events
subscription.created
Fired when a new subscription is created.
{
"id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000004",
"type": "subscription.created",
"created_at": "2026-02-16T14:30:00.000Z",
"data": {
"customer": {
"email": "john@example.com",
"stripe_customer_id": "cus_abc123"
},
"subscription_id": "sub_xyz789",
"status": "active",
"current_period_start": "2026-02-16T00:00:00.000Z",
"current_period_end": "2026-03-16T00:00:00.000Z"
}
}
subscription.renewed
Fired when a recurring subscription payment succeeds.
Payload is similar to payment.completed with additional subscription details.
subscription.canceled
Fired when a subscription is fully canceled.
{
"id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000005",
"type": "subscription.canceled",
"created_at": "2026-02-16T14:30:00.000Z",
"data": {
"customer": {
"email": "john@example.com",
"stripe_customer_id": "cus_abc123"
},
"subscription_id": "sub_xyz789",
"canceled_at": "2026-02-16T14:30:00.000Z"
}
}
subscription.paused / subscription.resumed
Fired when a subscription is paused or reactivated. Payload includes subscription_id and customer details.
subscription.past_due
Fired when a recurring payment fails. This is a warning that the subscription may be at risk. Payload includes the failed amount and invoice_id.
customer.created
Fired when a new customer is created for the first time.
{
"id": "evt_a1b2c3d4-e5f6-7890-abcd-000000000006",
"type": "customer.created",
"created_at": "2026-02-16T14:30:00.000Z",
"data": {
"customer": {
"email": "john@example.com",
"name": "John Doe",
"stripe_customer_id": "cus_abc123"
}
}
}
HTTP Specification
Request headers
| Header | Value |
|---|---|
Content-Type | application/json |
X-Stryhub-Signature | t=1708100000,v1=hex_signature |
X-Stryhub-Event | Event type (e.g., payment.completed) |
X-Stryhub-Delivery | Unique delivery UUID |
User-Agent | Stryhub-Webhooks/1.0 |
Expected response
Your endpoint should return a 2xx status code to acknowledge receipt. The response body is logged but not processed.
| Status Code | Meaning |
|---|---|
200-299 | Success — delivery marked as delivered |
300-499 | Failure — delivery will be retried |
500+ | Failure — delivery will be retried |
| Timeout (15s) | Failure — delivery will be retried |
Timeout
Webhook requests have a 15-second timeout. If your endpoint doesn't respond within 15 seconds, the delivery is treated as a failure and will be retried.
200 response and process it asynchronously in a background job.IP addresses
Webhook requests originate from stryhub's servers. If you need to whitelist IPs, contact support for the current list of outbound IP addresses.