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 Biteship's API continuously.
This article will help you understand:
- What is Biteship Webhook
- Benefits of using Webhook for operations
- Events supported by Biteship Webhook
- Steps to configure
- Webhook security and verification
- Data handling tips (Best Practices)
1. What is Biteship Webhook?
Webhook is a mechanism used by Biteship to automatically send data or information to your server/application immediately after an event occurs.
If a regular API requires you to "ask" (pull data), 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 Webhook
By enabling Webhook, 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 burden the 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 the data between Biteship dashboard and your internal database is always aligned.
3. Events Supported by Biteship Webhook
Biteship provides notifications for various important events in the delivery cycle, including:
- order.status: Sent every time 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. Ensure the URL is publicly accessible and uses the HTTPS protocol.
Step 2: Open the Webhook Page in Biteship Dashboard
Log in to your Biteship account, then navigate to the Integrations menu. Select the For Developer 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 information (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 added 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 the delivery history along with response status, request payload, and response payload. If a delivery fails, use the Resend button to manually resend.
5. Webhook Security
To ensure that the data entering your server truly comes 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, so you can validate that the request is from Biteship.
- HTTPS: Ensure 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 heavy logical processing.
- Queue: Use a queue 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 so data does not get mixed.
7. FAQ About Webhook
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.
Which events can be monitored via Webhook?
For sellers’ needs, available events are order.status (shipping status changes), order.waybill_id (tracking number issuance), and order.price (order price updates).
8. Conclusion
Webhook is the best solution for businesses that want to provide a responsive customer experience through automatic shipping status updates. With proper configuration, your system will always be 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.