Webhooks

Overview

Webhooks are HTTP callbacks that Nilo uses to notify your system about events in real-time. Unlike regular API endpoints where you make requests to Nilo, webhooks are endpoints that you must implement in your system to receive notifications from Nilo.

Important Implementation Requirements

1. Endpoint Availability: Your endpoints must be publicly accessible
2. Path Structure: You must implement the exact paths as specified by Nilo
3. Response Time: Your endpoints should respond within a reasonable timeout period
4. Response Code: Must return HTTP 200 to acknowledge receipt
5. Contract Compliance: Must accept the exact request body structure as specified

Available Webhooks

Order Created Webhook

POST/webhooks/order

This webhook is triggered when a new order is created in the Nilo platform. Your system must implement this endpoint to receive order notifications.

Request Body Structure

Field	Type	Description
id	integer	Order ID in Nilo system
buyer	object	Information about the buyer
address	object	Delivery address details
products	array	List of ordered products
promotions	object	Contains rewards and discounts applied to order
status	string	Order status (always "PENDING" for new orders)

Promotions Structure

Field	Type	Description
rewards	array	List of rewards for the order
discounts	array	List of discounts for the order

Reward Structure

Field	Type	Description
promoInternalCode	string	Internal code of the promotion
quantity	number	Quantity of products that to be rewarded
products	array	List of products that to be rewarded (always one)

Reward Product Structure

Field	Type	Description
internalCode	string	Internal code of the product
units	number	Units of the product

Discount Structure

Field	Type	Description
promoInternalCode	string	Internal code of the promotion
appliedDiscountPercentage	number	Applied discount percentage
appliedDiscountAmount	number	Applied discount amount
products	array	List of products to be discounted

Discount Product Structure

Field	Type	Description
internalCode	string	Internal code of the product
units	number	Units of the product

Example Request Body

{
  "id": 10,
  "buyer": {
    "storeCode": "10",
    "routeCode": "10"
  },
  "address": {
    "internalCode": "1234",
    "addressLine": "25 de mayo 1200, Buenos aires, Argentina",
    "apartmentNumber": "2",
    "zipCode": "2400"
  },
  "products": [
    {
      "code": "22222.1",
      "units": 2,
      "quantity": 10,
      "unitFinalPrice": {
        "value": 0.9,
        "text": "USD 0.9"
      },
      "unitPrice": {
        "value": 1,
        "text": "USD 1"
      },
      "subtotal": {
        "value": 10,
        "text": "USD 10"
      },
      "total": {
        "value": 9,
        "text": "USD 9"
      }
    }
  ],
  "promotions": {
    "rewards": [
      {
        "promoInternalCode": "5425",
        "quantity": 1,
        "products": [
          {
            "internalCode": "45678",
            "units": 1
          }
        ]
      }
    ],
    "discounts": [
      {
        "promoInternalCode": "1234",
        "appliedDiscountPercentage": 10,
        "appliedDiscountAmount": 0.1,
        "products": [
          {
            "internalCode": "22222.1",
            "units": 2
          }
        ]
      }
    ]
  },
  "status": "PENDING",
  "createdAt": "2025-12-03T10:15:30Z"
}

Order Cancelled Webhook

PUT/webhooks/order

This webhook is triggered when an order is cancelled in the Nilo platform. Your system must implement this endpoint to receive cancellation notifications.

Request Body Structure

Field	Type	Description
id	integer	Order ID in Nilo system
status	string	Always "CANCELLED" for cancellation events
reason	string	Human-readable reason for cancellation
code	string	Cancellation code (e.g., "NEW_ORDER")
buyer	object	Information about the buyer

Example Request Body

{
  "id": 10,
  "status": "CANCELLED",
  "reason": "I will place a new order",
  "code": "NEW_ORDER",
  "buyer": {
    "storeCode": "1234"
  }
}

Store User Events Webhook

POST/webhooks/store/user

This webhook is triggered for store user-related events (creation/deletion). Your system must implement this endpoint to receive user event notifications.

Request Body Structure

Field	Type	Description
subject	string	Event type ("user-created" or "user-deleted")
store	object	Store information
user	object	User information

Example Request Body

{
  "subject": "user-created",
  "store": {
    "id": 1,
    "internalCode": "123565"
  },
  "user": {
    "username": "+5042345213343",
    "name": "seller name"
  }
}

Support Ticket Creation Webhook

POST/webhooks/support/create-ticket

This webhook is triggered when a new support ticket is created in the Nilo platform. Your system must implement this endpoint to receive support ticket notifications.

Request Body Structure

Field	Type	Required	Description
ticket_id	string	Yes	Unique identifier for the ticket
client_internal_code	string	Yes	Internal code of the client
client_name	string	Yes	Name of the client
phone_number	string	No	Contact phone number
email	string	No	Contact email address
description	string	Yes	Description of the support issue
issue_type	string	Yes	Type of support issue

Example Request Body

{
  "ticket_id": "1122",
  "client_internal_code": "1122",
  "client_name": "Nilo Store",
  "phone_number": "+5042345213343",
  "email": "seller@nilo.com",
  "description": "I need support for my account",
  "issue_type": "Account support"
}

Support Ticket Additional Info Received Webhook

POST/webhooks/support/ticket-additional-info-received

This webhook is triggered when there is a reply to a request for additional information for a support ticket. Your system must implement this endpoint to receive these notifications.

Request Body Structure

Field	Type	Required	Description
ticket_id	string	Yes	Ticket ID generated by Nilo
external_ticket_id	string	No	Ticket ID generated by the ticket provider (if available)
client_internal_code	string	Yes	Internal code of the client
client_email	string	Yes	Client's email address
response	string	Yes	The reply to the customer's request for additional information

Example Request Body

{
  "ticket_id": "1122",
  "external_ticket_id": "EXT-5678",
  "client_internal_code": "1122",
  "client_email": "seller@nilo.com",
  "response": "Here is the additional information you requested"
}

Response

Your endpoint should return a 200 status code to acknowledge successful receipt of the webhook notification.

Implementation Guidelines

1. Endpoint Setup

   • Implement all required webhook endpoints
   • Use exact paths as specified
   • Accept POST/PUT methods as indicated
   • Return HTTP 200 on successful receipt

2. Error Handling

   • Implement proper error handling
   • Log webhook payloads for debugging
   • Handle duplicate notifications gracefully
   • Implement retry mechanisms if needed

3. Security Considerations

   • Validate webhook source
   • Protect endpoint access
   • Implement HTTPS
   • Monitor for abuse

4. Performance

   • Process webhooks asynchronously
   • Respond quickly (under 10 seconds)
   • Scale for high volume
   • Monitor endpoint health

Testing Webhooks

1. Setup Testing Environment

   • Use a publicly accessible endpoint
   • Test with sample payloads
   • Verify response codes
   • Monitor processing

2. Common Test Scenarios

   • New order creation
   • Order cancellation
   • User events
   • Error conditions

Best Practices

1. Reliability

   • Implement idempotency
   • Store raw webhook data
   • Process asynchronously
   • Handle retries properly

2. Monitoring

   • Log all webhook calls
   • Track response times
   • Monitor error rates
   • Set up alerts

3. Maintenance

   • Regular testing
   • Update implementations
   • Monitor changes
   • Maintain documentation