Thunder Docs
  1. Custom stores integration
  • Custom stores integration
    • Thunder Script Integration
    • Webhooks Integration
    • Orders Webhook
      POST
    • Products Webhook
      POST
  1. Custom stores integration

Webhooks Integration

Webhooks#

Thunder Webhooks allow your application to keep Thunder synchronized with your store by sending product and order updates in real time.
Whenever products or orders change, your application should notify Thunder by sending the appropriate webhook payload.
Thunder uses this information to:
Build your product catalog
Track purchases
Match orders with previously tracked visitors
Attribute revenue to marketing campaigns
Calculate marketing performance
Keep your Thunder dashboard up to date
Important
Thunder Webhooks work together with the Thunder Script. The script tracks visitors and attribution, while webhooks provide product and order data. Both integrations are required for complete attribution.

Table of Contents#

How Thunder Uses Webhooks
Event Flow
Authentication & Thunder Security
Supported Events
Schemas
Best Practices
Retry Behavior
Idempotency
HTTP Status Codes
Troubleshooting
FAQ
Integration Checklist
Next Steps

How Thunder Uses Webhooks#

Thunder combines visitor attribution collected by the Thunder Script with the order data received through Webhooks.
Visitor lands on website
          │
          ▼
Thunder Script Detects (Visit&Login)
          │
          ▼
Customer places an order
          │
          ▼
Your backend sends
order.create
          │
          ▼
Thunder matches the order
with the visitor
          │
          ▼
Purchase is attributed
to the correct campaign
          │
          ▼
Dashboard is updated
Without Webhooks, Thunder cannot associate purchases with your products or calculate attribution.

Event Flow#

A typical customer journey generates webhook events in the following order.
product.create
      │
      ▼
product.update (optional)
      │
      ▼
order.create
      │
      ▼
order.update (optional)
      │
      ▼
order.refunded (if applicable)
Not every order will generate every event.
For example, an order that is never refunded will never send an order.refunded event.

Authentication & Thunder Security#

Thunder secures it's Webhooks by using headears, We did not receive data through our Webhooks without the headears signature which we provide to our users.
thunder-webhook-security-dark.png

Supported Events#

Order Events#

EventTriggerPurpose
order.createA new order is createdCreates a purchase in Thunder
order.updateOrder details changeUpdates an existing purchase
order.refundedRefund issuedUpdates revenue and attribution

order.create#

Send this event immediately after a new order has been successfully created.
Thunder uses this event to:
Create the purchase
Associate the customer
Match attribution
Calculate revenue
Update reporting
This event should only be sent once for each order.
Schema:
Order
Customer
Product

order.update#

Send this event whenever an existing order changes.
Examples include:
Fulfilled
Shipped
Delivered
Cancelled
Edited
Thunder updates the existing purchase without creating a duplicate.
Schema:
Order
Customer
Product

order.refunded#

Send this event whenever an order is refunded.
Thunder updates:
Revenue
Attribution
ROAS
Dashboard analytics
Schema:
Order
Customer
Product

Product Events#

EventTriggerPurpose
product.createProduct createdCreates a product inside Thunder
product.updateProduct updatedUpdates an existing product

product.create#

Send this event whenever a new product becomes available.
Thunder stores the product information so purchases can later be matched correctly.
Schema:
Product

product.update#

Send this event whenever product information changes.
Examples include:
Name
Price
SKU
Images
Inventory
Status
Thunder updates the existing product.
Schema:
Product

Best Practices#

To ensure accurate attribution and reliable synchronization:
Send webhook events immediately after changes occur.
Use permanent Order IDs.
Use permanent Product IDs.
Retry failed requests.
Never generate new IDs for updates.
Validate payloads before sending.
Keep customer information consistent across events.

Schemas#

NameDecription
OrderThe Orders Payload schema through it's Webhook
ProductThe Product schema through the Orders Webhook
CustomerThe Customer schema through the Orders Webhook
ProductsThe Products Payload schema through it's Webhook

Retry Behavior#

If Thunder cannot process your request due to a temporary failure, retry the request.
Recommended retry schedule:
After 1 minute
After 5 minutes
After 15 minutes
After 1 hour
After 24 hours
Use exponential backoff whenever possible.
Do not retry requests that return permanent validation errors such as invalid payloads.

Idempotency#

Webhook events should be idempotent.
Thunder identifies resources using your unique identifiers.
For example:
Sending the same order.update multiple times updates the existing order.
Sending the same product.update multiple times updates the existing product.
Always use stable IDs.
Do not generate new IDs for updates.

HTTP Status Codes#

StatusMeaning
200 OKRequest processed successfully
400 Bad RequestInvalid payload
401 UnauthorizedInvalid or missing API Key
403 ForbiddenAuthentication failed
404 Not FoundInvalid endpoint
409 ConflictDuplicate or conflicting resource
500 Internal Server ErrorTemporary Thunder error

Troubleshooting#

Unauthorized Request (401)#

Cause:
Missing API Key
Invalid API Key
Solution:
Verify your Authorization or x-api-key header.

Invalid Payload (400)#

Cause:
Payload does not match the required schema.
Solution:
Validate the request body against the corresponding Thunder schema.

Duplicate Orders#

Cause:
Changing Order IDs between updates.
Solution:
Always reuse the same Order ID.

Missing Attribution#

Cause:
The customer was never tracked by the Thunder Script before the purchase.
Solution:
Ensure the Thunder Script is installed on your storefront and visitors are tracked before purchases occur.

FAQ#

Can I resend an order?#

Yes.
Thunder updates the existing order using its Order ID.

Can I resend product updates?#

Yes.
Product updates are idempotent.

Should I send fulfilled orders?#

Yes.
Use the order.update event.

Should I send partial refunds?#

Yes.
Each refund should trigger an order.refunded event with the updated order data.

Do I need both Thunder Script and Webhooks?#

Yes.
The Thunder Script tracks visitors and attribution.
Webhooks send product and order information.
Both integrations are required for complete marketing attribution.

Integration Checklist#

Before going live, verify the following:
Thunder Script installed
API Key generated
Authentication configured
Product webhooks implemented
Order webhooks implemented
Refund webhooks implemented
Payloads validated
Retry logic implemented
Orders appear in Thunder
Products appear in Thunder
Attribution appears correctly in the dashboard

Next Steps#

Once your webhook integration is complete, continue with:
Order Schema
Product Schema
Customer Schema
Products Schema
These documents describe the required payloads for each webhook event in detail.
Modified at 2026-07-06 22:39:08
Previous
Thunder Script Integration
Next
Orders Webhook
Built with