To automatically integrate your application system or online store with Biteship services, you can use the Webhook feature.
This feature allows your system to receive real-time notifications about shipping status changes without having to manually check the Biteship API continuously.
This article will help you understand:
- What Biteship Webhook is
- Benefits of using Webhooks for operations
- Events supported by Biteship Webhooks
- Steps to configure
- Webhook security and verification
- Data handling tips (Best Practices)
1. What Is Biteship Webhook?
A webhook is a mechanism used by Biteship to automatically send data or information to your server/application immediately after an event occurs.
While a regular API requires you to "ask" (pull data), a webhook works by "notifying" (push data). For example, when a package status changes, Biteship will immediately send that status data to the URL you specify.
2. Benefits of Using Webhooks
By activating Webhooks, your business will gain the following efficiencies:
- Real-Time Updates: Order status in your application automatically updates when the courier updates the status in the field.
- Resource Efficiency: You don’t need to repeatedly poll the API, which can strain your server.
- Advanced Automation: You can trigger other automatic actions, such as sending email or WhatsApp notifications to buyers when the package status changes.
- Data Synchronization: Ensures data between the Biteship dashboard and your internal database is always aligned.
3. Events Supported by Biteship Webhooks
Biteship provides notifications for various important events in the shipping cycle, including:
- order.status: Sent whenever there is a change in shipping status, along with courier information, tracking number, and driver details (for instant services).
- order.waybill_id: Sent when the official tracking number from the courier has been issued.
- order.price: Sent when there is an update to the order price.
4. How to Configure Webhook
Step 1: Prepare the Endpoint URL
Prepare a URL on your server that is ready to receive data in JSON format via the POST method. Make sure the URL is publicly accessible and uses the HTTPS protocol.
Step 2: Open the Webhook Page in the Biteship Dashboard
Log in to your Biteship account, then navigate to the Integrations menu. Select the For Developers tab, then click the Webhook card.
Step 3: Add a New Webhook
Click the Add Webhook button. In the modal that appears, fill in the following fields:
- Webhook Name — identify your webhook (required)
- Webhook Description — additional remarks (optional)
- Webhook URL — your server endpoint address (required)
- Event — select one or more events to monitor (order.status, order.waybill_id, order.price)
In the Headers (Optional) section, you can fill in the Headers Signature Key and Headers Signature Secret for additional security. Click Create to save.
Step 4: Verify via Events Log
Once the webhook is active, monitor notification deliveries through the Events Log tab on the Webhook page. Here you can see delivery history along with response status, request payload, and response payload. If any delivery fails, use the Resend button to manually resend.
5. Webhook Security
To ensure that the data coming to your server truly originates from Biteship, we recommend:
- Headers Signature Key & Secret: When creating a Webhook, fill in the Headers Signature Key and Headers Signature Secret fields. These values will be sent as HTTP headers on every request to your server, allowing you to validate that the request is from Biteship.
- HTTPS: Make sure your endpoint URL uses a secure protocol (HTTPS). URLs not using HTTPS are at risk of data leakage.
6. Handling Tips (Best Practices)
- Quick Response: Ensure your server immediately returns an HTTP 200 OK response after receiving data, before performing any heavy logical processing.
- Queue: Use a queuing system if you need to perform lengthy data processing, so the connection does not timeout.
- Idempotency: Make sure your system can handle cases where the Webhook sends the same data more than once.
- Separate Environments: Create separate Webhooks for development (test) and production (live) environments to avoid data mixing.
7. FAQ About Webhooks
What if Webhook delivery fails?
If delivery fails (server does not respond or returns an error), you can view failure details in the Events Log tab and manually resend using the Resend button.
Can one account have more than one Webhook?
Yes, you can create multiple Webhooks as needed, for example to separate test and live environments. Each Webhook can be configured with different URLs and event combinations.
What events can be monitored via Webhook?
For sellers' needs, the available events are order.status (shipping status changes), order.waybill_id (tracking number issuance), and order.price (order price updates).
8. Conclusion
Webhooks are the best solution for businesses wanting to provide a responsive customer experience through automatic shipping status updates. With proper configuration, your system will always stay synchronized with the latest data from Biteship in real-time.
If you need technical assistance regarding Webhook integration, please refer to the Biteship API Documentation or contact our support team at support@biteship.com.