Storrik DocsWebhook Overview
Learn how to use webhooks on storrik
Webhooks
Storrik sends webhook events to notify your system about transaction lifecycle changes.
Each webhook is delivered as a signed HTTP POST request with a JSON payload.
All transaction webhooks share the same envelope format and differ only by type and the transaction state.
Common Webhook Envelope
All webhook events follow this structure:
{
"id": "evt_xxx",
"object": "event",
"type": "transaction.created",
"api_version": "2025-11-07.alpha",
"created": 1768293724,
"livemode": false,
"data": {
"object": { ... }
}
}Envelope Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique event ID |
object | string | Always "event" |
type | string | Event type |
api_version | string | API version used |
created | number | Unix timestamp (seconds) |
livemode | boolean | Whether event was generated in live mode |
data.object | object | The resource associated with the event |
Transaction Object
Both transaction.created and transaction.succeeded include a transaction object.
{
"id": "txn_xxx",
"object": "transaction",
"status": "incomplete",
"amounts": {
"gross": 3400,
"tax": 0,
"discount": 0,
"net": 3400,
"currency": "USD"
},
"customer": {
"id": "CUS_xxx",
"email": "customer@example.com",
"country": "US"
},
"items": {
"product_id": "prod_xxx",
"variant_id": "var_xxx"
},
"tax": {
"collected": false,
"amount_cents": 0
},
"metadata": {},
"created": 1768293724
}Transaction Fields
| Field | Type | Description |
|---|---|---|
id | string | Transaction ID |
object | string | Always "transaction" |
status | string | Current transaction state |
amounts.gross | number | Total amount before fees and tax (cents) |
amounts.tax | number | Tax amount collected (cents) |
amounts.discount | number | Discount applied (cents) |
amounts.net | number | Net amount after deductions (cents) |
amounts.currency | string | ISO currency code |
customer.id | string | Customer ID |
customer.email | string | null |
customer.country | string | null |
items.product_id | string | null |
items.variant_id | string | null |
tax.collected | boolean | Whether tax was collected |
tax.amount_cents | number | Tax amount in cents |
metadata | object | Custom metadata |
created | number | Unix timestamp (seconds) |
Events
transaction.created
Sent when a transaction is first created.
At this stage, the transaction is not yet completed.
Status
status:"incomplete"
Example Payload
{
"id": "evt_123",
"object": "event",
"type": "transaction.created",
"api_version": "2025-11-07.alpha",
"created": 1768293724,
"livemode": false,
"data": {
"object": {
"id": "txn_123",
"object": "transaction",
"status": "incomplete",
"amounts": {
"gross": 3400,
"tax": 0,
"discount": 0,
"net": 3400,
"currency": "USD"
},
"customer": {
"id": "CUS_123",
"email": "customer@example.com",
"country": null
},
"items": {
"product_id": null,
"variant_id": null
},
"tax": {
"collected": false,
"amount_cents": 0
},
"metadata": {},
"created": 1768293724
}
}
}transaction.succeeded
Sent when a transaction has been successfully completed and funds are captured.
Status
status:"succeeded"
Example Payload
{
"id": "evt_456",
"object": "event",
"type": "transaction.succeeded",
"api_version": "2025-11-07.alpha",
"created": 1768293800,
"livemode": false,
"data": {
"object": {
"id": "txn_456",
"object": "transaction",
"status": "completed",
"amounts": {
"gross": 3400,
"tax": 0,
"discount": 0,
"net": 3400,
"currency": "USD"
},
"customer": {
"id": "CUS_456",
"email": "customer@example.com",
"country": "US"
},
"items": {
"product_id": "prod_123",
"variant_id": "var_123"
},
"tax": {
"collected": false,
"amount_cents": 0
},
"metadata": {
"invoiceId": "03ff07b1-2ad9-47f2-8c90-5ac3da9f1d32"
},
"created": 1768293800
}
}
}Verifying Webhooks
Non-Discord webhooks include the following HTTP headers:
Storrik-SignatureStorrik-EventStorrik-Webhook-Id
The request body is signed using HMAC SHA-256 with your webhook secret.
To verify a webhook, compute an HMAC SHA-256 signature of the raw request body using your webhook secret and compare it to the value provided in the Storrik-Signature header.
If the signatures match, the webhook payload can be trusted as coming from Storrik.