Webhook Events
You can set webhooks through API that enable you to receive notifications about events that happen in your stores.
These are the events available to retrieve with webhooks:
NEW_ORDER: New ordersNEW_ORDER_SCHEDULED: Early notification for scheduled orders. Sent when the customer schedules an order for a future time, ahead of theNEW_ORDERthat arrives at release. See NEW_ORDER_SCHEDULEDNEW_ORDER_SCHEDULED_CANCELLED: Sent when a scheduled order is cancelled before it is released to your store (i.e. beforeNEW_ORDER). See NEW_ORDER_SCHEDULED_CANCELLEDORDER_EVENT_CANCEL: Order cancellation events. See Cancellation EventsORDER_OTHER_EVENT: Order events. See Order EventsMENU_APPROVED: Menu approval events.MENU_REJECTED: Menu rejection events.MENU_ERROR: Menu error events.PING: This event enables the health check procedureSTORE_CONNECTIVITY: This event enables the store connectivity information process. (When the store is available or unavailable to operate)ORDER_RT_TRACKING: This event enables the tracking process.STORE_PROVISIONING_STATUS: Notifies when a batch provisioning or deprovisioning operation completes. See STORE_PROVISIONING_STATUS
Use the endpoints of the Webhooks resource to register and test webhooks in your stores.
Important
If you want to check the IP's from where the information is sent, you should ask your Project Manager
Webhook event payloads
NEW_ORDER
The NEW_ORDER event is going to send the same information that we can get from the getOrders endpoint for the order that fires the event. We can find more information about the body at the API reference
NEW_ORDER_SCHEDULED
The NEW_ORDER_SCHEDULED event is an early notification that a customer scheduled an order for a future time (place_at). Unlike NEW_ORDER, it is sent when the scheduled order is created — ahead of the fulfillment window — so your POS can plan for it in advance. It is opt-in per store and purely additive: it does not replace or alter NEW_ORDER.
The final order, with confirmed prices and totals, is delivered later through NEW_ORDER when the order is released to your store (at the scheduled time / store opening). NEW_ORDER drives the order lifecycle exactly as before.
The payload carries the order in the full getOrders shape plus a top-level action field. Only the monetary values are zeroed: totals, charges/fees, item prices and tips are sent as 0 / empty because at creation they are still provisional (Rappi recomputes them at release). Every other field comes through with its real value, exactly as in NEW_ORDER — including a top-level customer object with personal data (PII) when available. The key fields:
| Field | Description |
|---|---|
actionstring | Always "scheduled" for this event. Lets you tell the early notification apart from a regular NEW_ORDER, which has no action field. |
order_detail.order_idstring | Rappi order id. |
order_detail.place_atstring | Date and time the customer scheduled the order for, in the store's local time (yyyy-MM-dd HH:mm:ss). |
order_detail.items[]array | Ordered products, with sku, name and quantity. Prices are 0 (provisional). |
customerobject | Customer data (first_name, last_name, email, phone_number, document_type, document_number), same as NEW_ORDER, when available. Contains PII. |
storeobject | Target store (internal_id / external_id). Note: in this event the store id lives here (top-level store), not in order_detail. |
Example body:
{ "order_detail": { "order_id": "2150558091", "place_at": "2026-07-22 17:35:00", "delivery_method": "delivery", "payment_method": "cash", "totals": { "total_order": 0, "total_to_pay": 0, "charges": {}, "other_totals": { "tip": 0, "total_rappi_pay": 0, "total_rappi_credits": 0 } }, "items": [ { "id": "729970", "name": "Product 8", "quantity": 4, "sku": "0007", "price": 0, "unit_price_with_discount": 0, "unit_price_without_discount": 0 } ] }, "customer": { "first_name": "...", "last_name": "...", "email": "...", "phone_number": "...", "document_type": "...", "document_number": "..." }, "store": { "internal_id": "900105814", "external_id": "900105814", "name": "..." }, "action": "scheduled" }
Subscribe with the Webhooks endpoints using "event": "NEW_ORDER_SCHEDULED". Stores not subscribed keep receiving only NEW_ORDER, with no changes.
Important
The monetary fields in NEW_ORDER_SCHEDULED are provisional and sent as zero. Use the NEW_ORDER delivered at release for the confirmed prices, totals and fees. NEW_ORDER_SCHEDULED is an additional notification and its delivery does not affect the order.
NEW_ORDER_SCHEDULED_CANCELLED
The NEW_ORDER_SCHEDULED_CANCELLED event notifies you that a scheduled order was cancelled before it was released to your store — it was cancelled while still waiting for its scheduled time, so it never entered the regular order flow and never triggered NEW_ORDER. Use it to close out the matching NEW_ORDER_SCHEDULED early notification.
If a scheduled order is cancelled after it has been released (after NEW_ORDER), it follows the regular ORDER_EVENT_CANCEL flow instead — not this event.
This event is opt-in per store (a separate subscription from NEW_ORDER_SCHEDULED).
| Field | Description |
|---|---|
actionstring | Always "cancelled" for this event. |
order_detail.order_idstring | Rappi order id (matches the earlier NEW_ORDER_SCHEDULED). |
order_detail.store_idstring | Store id. |
order_detail.place_atstring | Scheduled date and time, in the store's local time (yyyy-MM-dd HH:mm:ss). |
Note — the store id lives in a different place per event: in the aviso (
NEW_ORDER_SCHEDULED) it is the top-levelstoreobject (there is noorder_detail.store_id); in this baja it isorder_detail.store_id. Keep this in mind when matching an aviso to its baja by store.
Example body:
{ "order_detail": { "order_id": "2150558091", "store_id": "900105814", "place_at": "2026-07-22 17:35:00" }, "action": "cancelled" }
ORDER_EVENT_CANCEL
The ORDER_EVENT_CANCEL event will send the payload with the following format:
{ "event": "canceled_with_charge", "order_id": "106", "store_id": "900109448" }
Where event represents the name of the cancelled event.
Where order_id represents the id of the order.
Where store_id represents the id of the store in the rappi app.
ORDER_OTHER_EVENT
The ORDER_OTHER_EVENT event will send the payload with the following format:
{ "event": "taken_visible_order", "order_id": "344949817", "store_id": "10000682", "event_time": "2023-05-04 12:01:22", "additional_information": { "courier_data": { "id": 729365, "phone": "3118012176", "full_name": "Daletzi Karina Olmedo Plata", "last_name": "Olmedo Plata", "first_name": "Daletzi Karina", "profile_pic": null }, "eta_to_store": 147, "storekeeper_name": "Daletzi Karina Olmedo Plata" } }
Where event represents the name of the event.
Where order_id represents the id of the order.
Where store_id represents the id of the store in the rappi app.
Where event_time represents the day and time of the event.
Where additional_information represents detailed information about the order.
MENU_APPROVED
The MENU_APPROVED event will send the payload with the following format:
{ "store_id": "900109448", "message": "Menu Approved" }
Where store_id represents the id of the store in the rappi app.
Where message is the menu approval message.
MENU_REJECTED
The MENU_REJECTED event will send the payload with the following format:
{ "store_id": "900109448" }
Where store_id represents the id of the store in the rappi app.
MENU_ERROR
The MENU_ERROR event will send the payload with the following format:
{ "store_id": "900109448", "reason": "..." }
Where store_id represents the id of the store in the rappi app.
Where reason is free text with the cause of the menu error; it may be empty. It is not localized: the text is not translated by language or country, and it may include product names exactly as the store entered them. It is meant to be shown to a person, not matched programmatically.
PING
The PING event will send the payload with the following format:
{ "store_id": 999 }
Where store_id represents the id of the store in the rappi app.
The response should have the following format:
{ "status": "OK", "description": "Store on" }
status: this field is required, if the value is null or different to OK it will be considered as unavailable store.
description: this field is optional.
HOW DOES PING WORK?
OBJECTIVE Detect when a store loses connectivity and turn it off when a ping change from positive to negative occurs, in order to prevent future cancellations due to said lack of connectivity in the store to accept the take. This Ping must be implemented for each store and not on a central server.
FUNCTION The monitor receives a notification every time a store goes from being pinged positive to negative. Realizing this, he immediately sends himself to suspend the shop in question. As an administrator you can configure the number of strikes to apply the negative ping rules.
- When a webhook is configured, the ping is sent every 3 minutes, in case of not having a webhook and using Order Pulling, it will be evaluated every 3 minutes.
- Depending on the number of negative pings configured, a Negative Ping incident is generated.
- The time range configured for grace time will be 1 minute.
- The current number of strikes is set to 2 for all allies.
- Only after validating the intermittence time, the connectivity loss or recovery incident is generated according to its definition.
Important
If you do not use webhooks, the evaluation every 3 minutes is done on the last time you downloaded orders, the grace time to determine if it is a negative ping is 1 minute
Important
There are stores that have split hours during the day, therefore, this schedule must be taken into account for the generation of the ping
Important
It is important to clarify that it does NOT apply to stores that have 24-hour hours
PING RULES
These are the following rules that we take into account
PING NEGATIVE This rule creates a Lost Connectivity incident, this incident is Status: Open awaiting a Positive Ping.
PING POSITIVE In this rule, an alert is triggered that looks for the Lost Connectivity incident Status: Open to change it to Status: Closed.
STORE_CONNECTIVITY
The STORE_CONNECTIVITY event will send the payload with the following format:
{ "external_store_id": "999", "enabled": false, "message": "The Store is not enabled to operate" }
Where external_store_id (String) represents the id of the store configurated on your side.
Where enabled (boolean) represents with a binary value of the store is available to operate or not.
Where message (String) represents a message informing if the store is available or not.
ORDER_RT_TRACKING
The ORDER_RT_TRACKING event will send the payload with the following format:
{ "lat": 123.3, "lng": 1234.5, "eta_in_millis": 330000, "eta_type": "PICKUP or DELIVERY", "order_id": 1234, "store_id": 1234, "courier_id": 1234, "created_at": "10/10/2023 12:00:20" }
lat (Double) is the courier's latitude. lng (Double) is the courier's longitude. eta_in_millis (Integer) is the distance in miles that the courier is from the restaurant. order_id (Integer) is the id of the order in the restaurant. courier_id (Integer) is the id of the courier who is with the delivery. store_id (String) represents the id of the store in the rappi app. created_at (String) is the date it was created.
Security
Our Public API has signatures for the security of its webhooks using a hash-based message authentication code (HMAC) with SHA-256 (Secure Hash Algorithm 2). Each request has its own signature which will come in the header with the name of Rappi-Signature and will have the following format
t=123456,sign=d74b65c2e68c1a84a4d5843a69ef5faf1d82f28df2dd3723e8e0dad9c54abc79
Important
Headers described in this portal are NOT case-sensitive. To get more information check this Link
Validating Your Signature
You can validate the signature that come in the header following the steps below
Important
To validate the signature, you will need the secret of your webhook.
-
Extract the timestamp and signatures from the header.
1.1 Separate with a comma "," to create a list.
1.2 Separate each element again with "=" to obtain
tand asign.t: Is the timestamp from the requestsign: Is the signature
-
Create the
signed_payloadstring by concatenating:-
The timestamp
-
The character
. -
The actual payload
Example:
123456.{ "message" : "this is an example" }
-
-
Compute an HMAC with the SHA256 hash function. Use the secret as the key, and use the
signed_payloadstring as the message to determine the expected signature. -
Compare the signature in the header with the expected signature.
You can now ensure that the information is valid.
Note
Make sure you are taking the payload string in the same format that it arrives in order to avoid any differences in the signature
Important
If the signature does not match, respond with a non-2xx status code and do not process the event. That way your endpoint only accepts webhooks that really come from Rappi. In the Homologation module of the Integrations Portal, the Validate HMAC signature capability tests both: it sends your endpoint a well-signed webhook, which you must accept, and one with an invalid signature, which you must reject. The test result shows how your endpoint responded to each one.
STORE_PROVISIONING_STATUS
The STORE_PROVISIONING_STATUS event fires when a batch provisioning or deprovisioning operation completes. It is configured at the integration level via POST /clients/{clientId}/webhooks with "event": "STORE_PROVISIONING_STATUS" in the request body.
The STORE_PROVISIONING_STATUS event will send the payload with the following format:
{ "batchId": "550e8400-e29b-41d4-a716-446655440000", "integrationId": "your-integration-id", "operation": "PROVISION", "results": [ { "storeId": "10", "integrationId": "your-integration-id", "brand": "YourBrand", "status": "ACTIVE", "httpCode": 201 }, { "storeId": "11", "integrationId": "your-integration-id", "brand": "YourBrand", "status": "FAILED", "errorMessage": "Store already exists", "httpCode": 409 } ], "timestamp": "2026-04-21T10:00:00Z" }
Where batchId is the unique identifier of the batch operation, matching the batchId returned in the provisioning/deprovisioning API response.
Where integrationId is the identifier of the integration that owns the stores.
Where operation indicates the type of operation performed:
| Value | Meaning |
|---|---|
PROVISION | The batch was a provisioning operation. |
DEPROVISION | The batch was a deprovisioning operation. |
Where results is an array of per-store outcomes:
| Field | Description |
|---|---|
results[].storeIdstring | Rappi store ID for which the operation was performed |
results[].integrationIdstring | Integration identifier |
results[].brandstring | Brand name resolved from Portal Partners |
results[].statusstring | Result of the operation for this store (see table below) |
results[].httpCodeinteger | HTTP status code returned by the underlying operation (e.g. 201, 204, 409) |
results[].errorMessagestring | Present only when status is FAILED; describes the failure reason |
Possible results[].status values:
| Value | Meaning |
|---|---|
ACTIVE | Provisioning completed successfully. The store is now integrated. |
INACTIVE | Deprovisioning completed successfully. |
FAILED | The operation failed. Check errorMessage and httpCode for details. |
Where timestamp is the ISO 8601 datetime when the event was generated.
