Use webhooks for routine order changes and keep status polling for reconciliation: checking that your records still match the panel. If you are building a small integration without a reliable public receiver yet, start with batched polling. Add webhooks when you can verify, save, and process their deliveries reliably.
The real question is what your customer sees after a change. An order may finish while your application is restarting, or a refund event may arrive twice because the first acknowledgement was lost. A useful order tracker handles both situations without showing stale information or applying the same update twice.
Give each method a clear job
- Polling: ask for the current picture
- Your application sends action=status and receives the state at that check. It is straightforward to start with, and multi-status accepts up to 100 order IDs per request. A shorter interval means more requests, including checks where nothing changed.
- Webhooks: receive selected changes
- NotPanel sends events to a registered HTTPS endpoint. Your receiver handles incoming work instead of repeatedly asking about every order. Deliveries do not use your client’s status-request allowance; your own receiver still needs capacity and monitoring.
- Reconciliation: repair missing information
- After an outage, or when a record looks stale, fetch current status for the affected orders. Keep this with webhooks: event notifications are best effort, an event can be missed, and delivery is not guaranteed. Retries are finite.
What the NotPanel API actually sends
This guide covers endpoints registered with webhook.add. Register a publicly reachable HTTPS URL and choose supported events, such as order.processing, order.in_progress, order.completed, order.partial, order.refunded, and order.refill_completed. Save the returned secret securely; webhook.list does not return it. Use webhook.list to inspect endpoint status and failures, and webhook.remove to remove an endpoint.
API deliveries contain an events array, even when there is only one event. Each event has its own id, event name, timestamp, and data. The outer deliveryId identifies the delivery. The following abbreviated example shows the shape, not a live order; the old example timestamps are not suitable for a freshness test.
{
"events": [
{
"id": "EXAMPLE_EVENT_ID",
"event": "order.completed",
"timestamp": 1700000000,
"data": { "order": 7001, "status_key": "completed" }
}
],
"timestamp": 1700000001,
"deliveryId": "EXAMPLE_DELIVERY_ID"
}Read event names from the verified body. API batches do not require X-Webhook-Event. Dashboard-created webhooks use a different single-event envelope, so use the matching contract rather than assuming the two payloads are interchangeable.
Verify the signature on the original body and check its timestamp.
Save the verified delivery before returning a 2xx response.
Apply each event once and recover missing state with status checks.
Make receiving an event safe
- Keep the raw body. Verify X-Webhook-Signature using the endpoint secret and X-Webhook-Timestamp, then enforce your receiver’s chosen timestamp tolerance. Parsing and reconstructing the body can change the signed bytes.
- Confirm X-Webhook-Delivery-Id matches the signed body’s deliveryId. Save the verified delivery before acknowledging it with a 2xx response. If you cannot safely accept it, let the sender retry rather than returning a success that loses the event.
- Process each events[].id once. Keep duplicate detection durable across restarts and coordinate it with the order update. Delivery-level duplicate detection alone is insufficient if the same event reaches multiple registered endpoints.
- Do slower work after acceptance. A valid signature establishes authenticity, not event order. When a delayed event conflicts with a newer state, reconcile with status instead of blindly replacing the customer’s current view.
Follow the signature verification walkthrough
What happens when your endpoint is unavailable?
A timeout or non-2xx response counts as a failed delivery. NotPanel retries API deliveries with increasing delays and pauses an API endpoint after 10 consecutive failures. A successful delivery resets its failure count. Monitor webhook.list; silence alone does not prove that no orders changed.
Keep a scheduled reconciliation pass over unresolved or stale orders. Batch up to 100 IDs, respect the account’s response headers and rate limits, and use the results to repair your own records. After fixing a paused receiver, verify that its registration is active before relying on new events. Do not assume historical failed deliveries will be replayed automatically.
Test the cases that a successful demo misses
Use synthetic payloads and a secret created for your own tests. No customer orders are needed to exercise receiver behaviour.
- Send the same verified delivery twice: one customer update should result.
- Send one event in two batches, then restart the receiver: the event should still be recognised.
- Alter one byte or use an old timestamp: verification should fail under your chosen policy.
- Simulate an outage and a delayed event: a status check should restore the current order view.
The same broad practices—subscribe selectively, verify secrets, and acknowledge promptly—appear in GitHub’s webhook guidance. Header names, payloads, and retry limits here follow NotPanel’s contract, not GitHub’s.
Frequently asked questions
Can I use only polling?
Yes. Batch status requests and choose an interval that fits your order volume and rate limits. Webhooks are useful when you can operate a reliable receiver; they are not required to place or track orders.
Do webhooks mean instant delivery or exactly one callback?
No. Network delays and retries can affect arrival, and duplicate deliveries can occur. Verify each delivery, process each event once, and keep status reconciliation for recovery.
Which headers should my API webhook receiver check?
Check X-Webhook-Signature and X-Webhook-Timestamp, then compare X-Webhook-Delivery-Id with the verified body’s deliveryId. Process the events array in that body.
Does a webhook make an uncertain add safe to repeat?
Webhook delivery and order placement are separate problems. Keep the original request_id and unchanged parameters when retrying an uncertain add, then save the recovered order ID.
Keep these references nearby: webhook contract · order status · timeout recovery.
