Getting Started with Webhooks

What are Webhooks?

Webhooks let SureDone automatically notify your external systems in real-time when something happens — like a new order coming in, an order being fulfilled, or an order status changing. Instead of repeatedly checking the SureDone API for updates (polling), your server receives a notification the moment an event occurs.

This is useful for connecting SureDone with your fulfillment systems, inventory management tools, accounting software, custom dashboards, or any system that needs to react to order activity immediately.

Technical documentation can be found here and here.

Accessing Webhooks

Navigate to Settings > Webhooks in the SureDone interface, or go directly to https://app.suredone.com/settings/webhooks.

The Webhooks page shows all of your configured endpoints, their health status, and quick access to delivery logs and statistics.

Adding a Webhook Endpoint

Click the "Add Endpoint" button to open the configuration modal. You'll need to provide:

• Endpoint URL (required) — The HTTPS URL where SureDone will send webhook events. This must be a publicly accessible URL using HTTPS. Private/internal network addresses are not allowed.
• Name (optional) — A friendly label to help you identify this endpoint (e.g., "Production Fulfillment" or "Analytics Pipeline").
• Description (optional) — A longer note describing what this endpoint is used for.
• Events to receive (required) — Select which event types this endpoint should receive. You must select at least one. You can use "Select All" to subscribe to all order events at once.

Available Event Types

Note: Product events (Created, Updated, Deleted, Inventory Changed) are coming soon and will appear in the event selection once available.

Save Your Signing Secret

After creating the endpoint, SureDone will display a signing secret (starts with whsec_). This is used to verify that incoming webhooks are genuinely from SureDone.

Important: Copy and save this secret immediately. You will not be able to view it again after closing the dialog. If you lose it, you can rotate it later from the endpoint settings (which will generate a new one and invalidate the old one).

Managing Endpoints

From the main Webhooks page, each endpoint is shown as a card displaying its name, URL, health status, and subscribed events.

Click the gear icon on any endpoint card to access management options:

• Edit — Change the endpoint's name, description, URL, or subscribed event types.
• Rotate Secret — Generate a new signing secret. The old secret is immediately invalidated. Use this if you suspect your secret has been compromised.
• Delete — Permanently remove the endpoint. SureDone will stop sending events to this URL immediately.

Endpoint Health

Each endpoint shows a health badge based on delivery success over the last 24 hours:

• Healthy — 98%+ delivery success rate with no pending retries.
• Degraded — 90-98% success rate, or has pending retries.
• Failing — Below 90% success rate. Check your endpoint's availability.
• Disabled — The endpoint has been disabled (either manually or automatically after prolonged failures).

Testing Your Endpoint

Before relying on webhooks in production, you can send a test event to verify your endpoint is working correctly.

1. Click the "Send Test" button on the endpoint card.
2. Select which event type you'd like to test.
3. SureDone sends a sample webhook with realistic (but synthetic) data to your endpoint.
4. The result is displayed immediately — you'll see the HTTP status code your server returned, the response time, and the response body.

Test events include a "test": true flag in the payload so your system can distinguish them from real events if needed.

Delivery Logs

Click "View Logs" on any endpoint card to see a detailed history of every delivery attempt. For each delivery you can see:

• Event type — Which event triggered the delivery (e.g., order.created).
• Status — Whether the delivery succeeded (2xx response) or failed.
• Response code — The HTTP status code your server returned.
• Timestamp — When the delivery was attempted.

Click on any delivery row to see full details including the request headers, request body (the full webhook payload), response headers, and response body from your server.

If a delivery failed, you can click "Retry" to resend it manually.

Statistics Dashboard

The Statistics view gives you an overview of your webhook activity across all endpoints. You can view stats for different time periods (24 hours, 7 days, 30 days, or 90 days) including:

• Total messages sent
• Successful vs. failed deliveries
• Success rate percentage

Tips & Best Practices

• Respond quickly — Your endpoint should return a 2xx HTTP status code within 15 seconds. If it takes longer, the delivery will be marked as failed and retried.
• Process asynchronously — Accept the webhook immediately (return 200), then process the data in a background job. This prevents timeouts.
• Handle duplicates — In rare cases, the same event may be delivered more than once. Each event includes a unique id field — store and check this ID to avoid processing the same event twice (idempotency).
• Combine with polling — For mission-critical workflows, we recommend using webhooks for real-time notifications and periodic API polling as a safety net. This ensures you never miss an event even if a webhook delivery fails after all retry attempts.
• Verify signatures — Use the signing secret to verify that webhooks are genuinely from SureDone. See the Webhook Events & Payload Reference guide for details.
• Fetch full data from the API — Webhook payloads contain key identifiers (like the order ID, channel, and status) but not the full order object. Use the order ID from the webhook to fetch complete order details via the SureDone API when needed.