API Reference

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 orders
• ORDER_EVENT_CANCEL: Order cancellation events. See Cancellation Events
• ORDER_OTHER_EVENT: Order events. See Order Events
• MENU_APPROVED: Menu approval events.
• MENU_REJECTED: Menu rejection events.
• PING: This event enables the health check procedure
• STORE_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.

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

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.

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.

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.

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.

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.

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.

1. 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.
2. Depending on the number of negative pings configured, a Negative Ping incident is generated.
3. The time range configured for grace time will be 1 minute.
4. The current number of strikes is set to 2 for all allies.
5. Only after validating the intermittence time, the connectivity loss or recovery incident is generated according to its definition.

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.

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.

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.

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

You can validate the signature that come in the header following the steps below

1. 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 t and a sign.

   • t: Is the timestamp from the request
   • sign: Is the signature

2. Create the signed_payload string by concatenating:

   • The timestamp

   • The character .

   • The actual payload

     Example:

     123456.{ "message" : "this is an example" }
     

3. Compute an HMAC with the SHA256 hash function. Use the secret as the key, and use the signed_payload string as the message to determine the expected signature.

4. Compare the signature in the header with the expected signature.

You can now ensure that the information is valid.

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[].storeId string	Rappi store ID for which the operation was performed
results[].integrationId string	Integration identifier
results[].brand string	Brand name resolved from Portal Partners
results[].status string	Result of the operation for this store (see table below)
results[].httpCode integer	HTTP status code returned by the underlying operation (e.g. 201, 204, 409)
results[].errorMessage string	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.