Webhook Events

Overview

Presto uses webhooks to send real-time notifications to your system when specific events occur, such as order creation, cancellation, or completion. This allows your application to react immediately to changes without needing to constantly poll API endpoints.

Setup

To receive webhooks, you must provide a publicly accessible HTTPS URL (your serviceUrl) to your Presto Partner Manager during the onboarding process. Presto will send POST requests with JSON payloads to this URL when events occur.

Security

• HTTPS Required: Your receiving endpoint must use HTTPS.
• Signature Verification: Verify that incoming webhook requests genuinely originate from Presto using the signature included in the request headers.
• IP Whitelisting: Consider whitelisting Presto's webhook source IP addresses as an additional security layer.

Request Headers

All webhook requests include the following headers:

Header	Value	Description
Authorization	Bearer {API_KEY}	Your API key for authentication
Accept	application/json	Indicates the request expects JSON responses
X-Origin	product	Identifies the source system sending the webhook (always product)

Receiving Webhooks

• Acknowledge Promptly: Your endpoint should respond quickly with a successful HTTP status code (200 OK, 204 No Content) to acknowledge receipt.
• Handle Failures: Implement logic to handle potential retries if your endpoint fails to respond.
• Idempotency: Design your webhook handler to be idempotent to avoid processing the same event multiple times.

Webhook Event Types

Presto will send a POST request to your configured serviceUrl with an event field identifying the type and a body field with the relevant payload.

Order Created Event

Event Type: order_created

Sent when a new order is created and assigned to your vendor/store.

Payload Fields

Field	Type	Description
order_reference	integer	The unique identifier for the newly created order.
items	array[object]	List of items included in the order.
items[].id	integer	Presto's internal ID for the item.
items[].order_item_id	integer	The unique identifier for this item within the order (order item id).
items[].quantity	integer	Quantity of this item ordered.
items[].price	number	Price per unit of this item at the time of order.
service_charge	number	Any applicable service charge.
delivery_charge	number	Any applicable delivery charge.
subtotal	number	The total cost of items before charges/discounts.
total	number	The final total amount for the order.
customer_id	integer	The unique identifier for the customer (user) who placed the order.
delivery_method	integer	Identifier for the delivery method (1 for delivery, 2 for pickup).
payment_method	string	Payment method key used for the order (e.g., cash, wallet).
vendor_id	integer	The unique identifier for the vendor/store.

Example

{
    "event": "order_created",
    "body": {
        "order_reference": 959,
        "items": [
            {"id": 35361, "order_item_id": 35361, "quantity": 1, "price": 10.5}
        ],
        "service_charge": 0,
        "delivery_charge": 10,
        "subtotal": 108.5,
        "total": 118.5,
        "customer_id": 3456,
        "delivery_method": 1,
        "payment_method": "cash",
        "vendor_id": 789
    }
}

---

Order Accepted Event

Event Type: order_accepted

Sent when an order is accepted by the vendor/store.

Payload Fields

Field	Type	Description
order_reference	integer	The unique identifier for the accepted order.
vendor_id	integer	The unique identifier for the vendor/store.

Example

{
    "event": "order_accepted",
    "body": {
        "order_reference": 959,
        "vendor_id": 789
    }
}

---

Order Ready Event

Event Type: order_ready

Sent when the order is marked as ready for pickup by the vendor/store.

Payload Fields

Field	Type	Description
order_reference	integer	The unique identifier for the order.
vendor_id	integer	The unique identifier for the vendor/store.

Example

{
    "event": "order_ready",
    "body": {
        "order_reference": 959,
        "vendor_id": 789
    }
}

---

Order Cancelled Event

Event Type: order_cancelled

Sent when an order is cancelled, either by the customer, Presto support, or due to timeout.

Payload Fields

Field	Type	Description
order_reference	integer	The unique identifier for the cancelled order.
reason	string	(Optional) Reason for cancellation, if available.
vendor_id	integer	The unique identifier for the vendor/store.

Example

{
    "event": "order_cancelled",
    "body": {
        "order_reference": 959,
        "vendor_id": 789
    }
}

Order Updated Event

Event Type: order_updated

Sent when details of an existing order are updated before it is finalized.

Payload Fields

Field	Type	Description
order_reference	integer	The unique identifier for the updated order.
items	array[object]	The updated list of items in the order.
items[].id	string	integer
items[].quantity	integer	Quantity of this item ordered.
items[].price	number	Price per unit of this item at the time of update.
service_charge	number	Any applicable service charge.
delivery_charge	number	Any applicable delivery charge.
subtotal	number	The total cost of items before charges/discounts.
total	number	The final total amount for the order.
wallet_amount	number	Amount paid using wallet (if applicable).
customer_id	integer	The unique identifier for the customer (user) who placed the order.
vendor_id	integer	The unique identifier for the vendor/store.

Example

{
    "event": "order_updated",
    "body": {
        "order_reference": 232911,
        "items": [
            {"id": 60728, "quantity": 2, "price": 100}
        ],
        "service_charge": 0,
        "delivery_charge": 10,
        "subtotal": 108.5,
        "total": 118.5,
        "wallet_amount": 0,
        "customer_id": 3456,
        "vendor_id": 789
    }
}

Driver Arrived at Vendor Event

Event Type: driver_arrived_at_vendor

Sent when the delivery driver arrives at the vendor/store to pick up the order.

Payload Fields

Field	Type	Description
order_reference	integer	The unique identifier for the order.
driver_id	integer	The unique identifier for the driver.
vendor_id	integer	The unique identifier for the vendor/store.

Example

{
    "event": "driver_arrived_at_vendor",
    "body": {
        "order_reference": 232911,
        "driver_id": 12345,
        "vendor_id": 789
    }
}

---

Order Picked Up Event

Event Type: order_picked_up

Sent when the order has been picked up by the driver from the vendor/store.

Payload Fields

Field	Type	Description
order_reference	integer	The unique identifier for the order.
driver_id	integer	The unique identifier for the driver.
vendor_id	integer	The unique identifier for the vendor/store.

Example

{
    "event": "order_picked_up",
    "body": {
        "order_reference": 232911,
        "driver_id": 12345,
        "vendor_id": 789
    }
}

---

Order Returned Event

Event Type: order_returned

Sent when an order is returned to the vendor/store (e.g., failed delivery).

Payload Fields

Field	Type	Description
order_reference	integer	The unique identifier for the order.
driver_id	integer	The unique identifier for the driver.
vendor_id	integer	The unique identifier for the vendor/store.

Example

{
    "event": "order_returned",
    "body": {
        "order_reference": 232911,
        "driver_id": 12345,
        "vendor_id": 789
    }
}

---

Order Completed Event

Event Type: order_completed

Sent when an order is successfully completed (delivered to the customer).

Payload Fields

Field	Type	Description
order_reference	integer	The unique identifier for the completed order.
driver_id	integer	The unique identifier for the driver.
wallet_amount	number	Amount paid using wallet.
cash_amount	number	Amount paid in cash.
payment_method	string	Payment method used (e.g., cash, wallet).
total	number	The final total amount for the order.
city_id	integer	The city identifier for the vendor.
vendor_id	integer	The unique identifier for the vendor/store.

Example

{
    "event": "order_completed",
    "body": {
        "order_reference": 974,
        "driver_id": 12345,
        "wallet_amount": 10,
        "cash_amount": 20,
        "payment_method": "cash",
        "total": 30,
        "city_id": 1,
        "vendor_id": 789
    }
}

---

Summary Table of All Events

Event Type	Description
order_created	New order assigned to your vendor/store
order_accepted	Order accepted by vendor/store
order_ready	Order ready for pickup
order_cancelled	Order was cancelled
order_updated	Order details updated
order_completed	Order delivered to customer
driver_arrived_at_vendor	Driver arrived at vendor/store
order_picked_up	Order picked up by driver
order_returned	Order returned to vendor/store