Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.quickshops.app/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks let you connect Quickshops to your own systems. Whenever something important happens in your store — a new order, a subscription cancellation, a failed payment — Quickshops sends an HTTP POST request to a URL you specify, so your external tools can react instantly.

​
Events you can subscribe to

EventWhen it fires
order.completedA customer completes a one-time purchase
subscription.createdA customer starts a new subscription
subscription.cancelledA subscription is cancelled
subscription.payment_failedA subscription renewal payment fails

​
Set up a webhook endpoint

1

Open Webhook settings

In your dashboard, go to Settings → Webhooks.
2

Add an endpoint

Click Add Endpoint and enter the URL of your server or service that will receive the events.
3

Select events

Choose which events you want this endpoint to receive. You can subscribe to one event or multiple.
4

Save

Click Save. Quickshops will start delivering matching events to your endpoint immediately.
If you need to test your endpoint before pointing it at production, tools like Webhook.site or ngrok let you inspect incoming payloads in real time.

​
Webhook payload format

Every webhook Quickshops sends is a JSON object with three top-level fields:
  • event — the name of the event that fired
  • timestamp — the time the event occurred, in ISO 8601 format
  • data — an object containing the details of the event
Here is an example payload for a completed order: 
{
  "event": "order.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "customerEmail": "customer@example.com",
    "productId": "prod_xyz",
    "amountInCents": 2900,
    "currency": "usd"
  }
}

​
Verifying webhook signatures

Every request Quickshops sends to your endpoint includes a signature header. You should use this signature to confirm the request genuinely came from Quickshops before acting on the payload.
Always verify the webhook signature before processing any event. Without verification, a malicious party could send fake payloads to your endpoint and trigger unintended actions in your system.
The signature is included in the X-Quickshops-Signature header of each request. To verify it, compute an HMAC of the raw request body using your webhook’s signing secret (shown in Settings → Webhooks when you view an endpoint), and compare it to the value in the header. Only process the event if they match.

​
Retries and failures

If your endpoint returns a non-2xx HTTP status code or doesn’t respond within the timeout window, Quickshops will retry delivery. You can view delivery attempts and their status for each endpoint from Settings → Webhooks.
Make your endpoint idempotent where possible — use the orderId or other unique identifiers in the payload to avoid processing the same event twice if a retry occurs.

​
Managing endpoints

You can add multiple endpoints to receive the same or different events. To edit, pause, or remove an endpoint, go to Settings → Webhooks and select the endpoint you want to manage.