Home Delivery Events
V2 webhooks can be configured in the Instabee merchant portal at partner.instabee.com.
Authentication
V2 webhooks support:
- HTTP Basic Auth - provide username and password in the portal
- OAuth2 - configure a token endpoint and credentials in the portal
V2 Request Headers
Every V2 callback includes these custom headers:
| Header | Description |
|---|---|
Budbee-Event | Event type (e.g. DELIVERED_TO_CONSUMER) |
Budbee-Event-ID | Unique event identifier |
Timestamp | Event time in ISO 8601 UTC |
V2 Events
| Event | Description |
|---|---|
PARCEL_CREATED | New parcel registered |
SORTED_AT_TERMINAL | Parcel sorted at terminal |
PARCEL_RECALLED | Parcel recalled by merchant |
HOME_DELIVERY_CHANGED | Home delivery details updated |
DELIVERED_TO_CONSUMER | Successfully delivered to consumer |
DELIVERY_FAILED | Delivery attempt failed |
DELIVERY_CANCELLED | Delivery cancelled |
RETURN_BOOKED_HOME | Home pickup return booked |
RETURN_HOME_PICKED_UP | Home pickup return collected |
RETURN_HOME_PICK_UP_FAILED | Home pickup return failed |
RETURN_HOME_PICK_UP_CANCELLED | Home pickup return cancelled |
RETURNED_TO_MERCHANT | Parcel returned to merchant |
LOCKER_CHANGED | Locker assignment changed |
DELIVERED_TO_LOCKER | Parcel placed in locker |
CONSUMER_PICKED_UP_FROM_LOCKER | Consumer collected from locker |
INJECTED_IN_LOCKER | Parcel injected directly into locker |
CHANGED_TO_LOCKER_DELIVERY | Delivery type changed to locker |
CHANGED_TO_HOME_DELIVERY | Delivery type changed to home |
RETURN_BOOKED_LOCKER | Locker return booked |
RETURN_LOCKER_PICK_UP_FAILED | Locker return pickup failed |
DELIVERY_VEHICLE_LOADED | Parcel loaded onto delivery vehicle |
V2 Event Payload
1{ 2 "eventId": "evt_abc123", 3 "eventType": "DELIVERED_TO_CONSUMER", 4 "timestamp": "2025-06-01T16:10:00Z", 5 "orderId": "order_abc123", 6 "packageId": "PKG-001", 7 "party": "BUDBEE", 8 "flow": "DELIVERY", 9 "eventData": { 10 "deliveredAt": "2025-06-01T16:10:00Z", 11 "recipientName": "Anna Svensson" 12 } 13}1{ 2 "eventId": "evt_abc123", 3 "eventType": "DELIVERED_TO_CONSUMER", 4 "timestamp": "2025-06-01T16:10:00Z", 5 "orderId": "order_abc123", 6 "packageId": "PKG-001", 7 "party": "BUDBEE", 8 "flow": "DELIVERY", 9 "eventData": { 10 "deliveredAt": "2025-06-01T16:10:00Z", 11 "recipientName": "Anna Svensson" 12 } 13}
V2 Payload Parameters
| param | Type | Description |
|---|---|---|
| eventId | string | Unique event identifier |
| eventType | string | Event type (see V2 Events table) |
| timestamp | string | ISO 8601 UTC timestamp |
| orderId | string | Order ID |
| packageId | string | Package identifier |
| party | string | Who triggered the event |
| flow | string | Delivery flow type |
| eventData | object | Event-specific data (varies by event type) |
V2 Data Types
| Field | Values | Description |
|---|---|---|
| party | BUDBEE, CONSUMER, MERCHANT | Who triggered the event |
| flow | DELIVERY, RETURN, C2C | The delivery flow |
| timestamp | ISO 8601 UTC | Date/time format used in V2 events (unlike the API which uses epoch ms) |