Quickstart

Precondiciones

Antes de comenzar, el equipo BipBip te provee los siguientes elementos de configuración. Necesitás todos antes de escribir tu primera línea de código:

• 1
  HMAC Secret — clave compartida para verificar la autenticidad del webhook (una por cuenta)
• 2
  API Key (X-Bipbip-Api-Key) — header de autenticación para llamar la REST API
• 3
  remoteId — identificador de tu tienda, definido por vos (ej: POS_TGU_001). Uno por tienda registrada.
• 4
  Base URL registrada — la URL base de tu servidor donde BipBip enviará los webhooks (debe ser públicamente accesible)

Los 4 pasos

1. 1

   Implementá el endpoint del webhook

   BipBip enviará POST {tuBaseUrl}/v1/order/{remoteId} cada vez que llegue una nueva orden para tu tienda. Tu endpoint debe:

   • Capturar el cuerpo crudo (raw body) antes de parsear el JSON
   • Verificar la firma HMAC (ver Verificación HMAC)
   • Devolver HTTP 200 con un JSON body que incluya remoteOrderId
   • Responder en menos de 30 segundos (BipBip toma cualquier respuesta lenta como fallo)
   Ojo: remoteOrderId es obligatorio en la respuesta

   Sin un remoteOrderId válido en el body, BipBip trata el delivery como fallido y reintenta. El 200 solo no alcanza. Ver BipBip sigue reintentando.
2. 2

   Verificá la firma HMAC

   Toda solicitud de BipBip incluye el header X-Bipbip-Signature-256 con una firma HMAC-SHA256. Verificar la firma garantiza que el request proviene de BipBip y no fue modificado en tránsito. Consultá la sección Verificación HMAC para los code samples.

3. 3

   Respondé con tu remoteOrderId

   Una vez verificada la firma y creada la orden en tu POS, devolvé HTTP 200 con:

   {
     "remoteOrderId": "POS-2026-04-11-00142"
   }

   Este valor es tu identificador interno del POS para esta orden. BipBip lo guarda y lo incluirá en todos los webhooks de cancelación subsiguientes para que puedas correlacionar.

4. 4

   Aceptá la orden llamando la REST API

   Después de recibir el webhook y responder 200, podés aceptar formalmente la orden llamando a POST /api/v1/Orders/{orderKey}/accept. Esto confirma que tu POS está listo para preparar el pedido.

   Este paso es opcional si tu tienda tiene auto-accept habilitado — en ese caso BipBip acepta la orden automáticamente al recibir tu 200.

   Node.js Python C# PHP

   Copy

   // Accept an order via the BipBip REST API — Node.js (Quickstart Step 4)
   // Call POST /api/v1/orders/{orderKey}/accept after receiving and verifying the webhook.
   // Requires Node.js 18+ (native fetch). No npm packages required.
   
   const API_BASE_URL = 'https://api.bipbip.com'; // Replace with the URL provided by BipBip
   const API_KEY      = process.env.BIPBIP_API_KEY;  // Your X-Bipbip-Api-Key header value
   
   /**
    * Accepts a BipBip order and sets your internal order ID (remoteOrderId).
    *
    * @param {string} orderKey      - The opaque BipBip order key (format: "ord_" + 16 base62 chars)
    * @param {string} remoteOrderId - Your POS's own internal order identifier
    * @param {string} idempotencyKey - A unique UUID for this request (reuse to safely retry)
    * @returns {Promise<object>} - The accepted order details from BipBip
    */
   async function acceptOrder(orderKey, remoteOrderId, idempotencyKey) {
     const url = `${API_BASE_URL}/api/v1/orders/${encodeURIComponent(orderKey)}/accept`;
   
     const response = await fetch(url, {
       method: 'POST',
       headers: {
         'Content-Type':    'application/json',
         'X-Bipbip-Api-Key': API_KEY,
         'Idempotency-Key':  idempotencyKey,  // Required on all mutations — enables safe retry
       },
       body: JSON.stringify({
         remoteOrderId, // Your internal POS order ID — BipBip will include it in cancel webhooks
       }),
     });
   
     if (!response.ok) {
       const error = await response.json().catch(() => ({}));
       throw new Error(`Accept failed: ${response.status} — ${JSON.stringify(error)}`);
     }
   
     return response.json();
   }
   
   // ── Usage example ─────────────────────────────────────────────────────────────
   // In your webhook handler (after HMAC verification):
   //
   // const { randomUUID } = require('crypto');
   //
   // async function handleOrderWebhook(req, res) {
   //   const order = JSON.parse(req.body.toString('utf8'));
   //
   //   // Step 1: Create the order in your POS system and get your internal ID
   //   const remoteOrderId = await yourPos.createOrder(order);
   //
   //   // Step 2: Accept the order on BipBip (use a stable UUID per attempt)
   //   const idempotencyKey = randomUUID();
   //   await acceptOrder(order.orderKey, remoteOrderId, idempotencyKey);
   //
   //   // Step 3: The webhook ACK body must include remoteOrderId
   //   res.status(200).json({ remoteOrderId });
   // }
   
   module.exports = { acceptOrder };

   Rate limits de la REST API

   Tenés 100 requests por minuto (ventana fija) y 1.000 por hora (ventana deslizante), por API Key. Si llegás al límite, BipBip te devuelve HTTP 429 — implementá exponential backoff con jitter y lo manejás sin problemas.

Sandbox — próximo

El algoritmo

BipBip firma cada request usando la siguiente fórmula:

message   = "{timestamp}.{rawBody}"
keyBytes  = UTF-8 bytes del HMAC secret
signature = "sha256=" + LOWERCASE(HEX(HMAC-SHA256(keyBytes, UTF8(message))))

Los headers relevantes en cada request son:

• X-Bipbip-Timestamp — Unix timestamp en segundos (número entero como string)
• X-Bipbip-Signature-256 — la firma en formato sha256=<hex>
• X-Bipbip-Delivery-Id — UUID único por envío (usar para deduplicación)
• X-Bipbip-Event-Type — tipo de evento. Posibles valores: order.created, order.cancelled, order.driver_assigned, order.delivered

Errores comunes (footguns)

Estos tres errores son la causa del 90% de los casos donde la firma no verifica. Revisálos antes de buscar otro problema.

Code samples

Seleccioná tu lenguaje. Todos los samples usan solo la librería estándar — no se necesitan dependencias externas.

// HMAC-SHA256 webhook signature verification — Node.js
// Verify that the webhook payload from BipBip is authentic before processing it.
// Requires Node.js 18+ (native fetch not needed here; only built-in crypto module).

const crypto = require('crypto');

/**
 * Verifies the HMAC-SHA256 signature of an incoming BipBip webhook.
 *
 * @param {string} secret         - HMAC secret provided by BipBip during onboarding
 * @param {string} timestamp      - Value of the X-Bipbip-Timestamp header (Unix seconds as string)
 * @param {Buffer|string} rawBody - Raw request body bytes BEFORE any JSON.parse() call
 * @param {string} signature      - Value of the X-Bipbip-Signature-256 header (e.g. "sha256=abc123...")
 * @returns {boolean}             - true if the signature is valid and the timestamp is within skew limit
 */
function verifyBipBipSignature(secret, timestamp, rawBody, signature) {
  // Step 1: Validate timestamp to prevent replay attacks.
  // Reject requests where the clock skew exceeds 300 seconds (5 minutes).
  const now = Math.floor(Date.now() / 1000);
  const ts = parseInt(timestamp, 10);
  if (Math.abs(now - ts) > 300) {
    return false;
  }

  // Step 2: Build the signed message exactly as BipBip does:
  //   message = "{timestamp}.{rawBody}"
  // IMPORTANT: rawBody must be the original bytes received over the wire.
  // Do NOT re-serialize a parsed JSON object — any whitespace/key-order
  // difference will produce a different signature.
  const message = `${timestamp}.${rawBody}`;

  // Step 3: Compute HMAC-SHA256 with the shared secret.
  // Both key and message are treated as UTF-8.
  // The digest is lowercased hex (BipBip never uses base64).
  const computed = crypto
    .createHmac('sha256', secret)
    .update(message, 'utf8')
    .digest('hex');

  // Step 4: Prepend the "sha256=" prefix to match the header value format.
  const expected = `sha256=${computed}`;

  // Step 5: Use a timing-safe comparison to prevent timing-oracle attacks.
  // crypto.timingSafeEqual requires two Buffers of equal length.
  const expectedBuf = Buffer.from(expected, 'utf8');
  const receivedBuf = Buffer.from(signature, 'utf8');
  if (expectedBuf.length !== receivedBuf.length) {
    return false;
  }
  return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}

// ── Express.js integration example ──────────────────────────────────────────
// In your Express app, use express.raw() (not express.json()) so that the
// raw body bytes are available for signature verification.
//
// app.use('/v1/order/:remoteId', express.raw({ type: '*/*' }), (req, res) => {
//   const secret    = process.env.BIPBIP_HMAC_SECRET;
//   const timestamp = req.headers['x-bipbip-timestamp'];
//   const signature = req.headers['x-bipbip-signature-256'];
//   const rawBody   = req.body; // Buffer when using express.raw()
//
//   if (!verifyBipBipSignature(secret, timestamp, rawBody, signature)) {
//     return res.status(401).json({ error: 'Invalid signature' });
//   }
//
//   const order = JSON.parse(rawBody.toString('utf8'));
//   const remoteOrderId = generateYourInternalOrderId(order);
//   res.status(200).json({ remoteOrderId });
// });

module.exports = { verifyBipBipSignature };

"""
HMAC-SHA256 webhook signature verification — Python 3.8+
Verify that the webhook payload from BipBip is authentic before processing it.
Uses only Python standard library (hmac, hashlib, time). No pip packages required.
"""

import hashlib
import hmac
import time


def verify_bipbip_signature(
    secret: str,
    timestamp: str,
    raw_body: bytes,
    signature: str,
    max_skew_seconds: int = 300,
) -> bool:
    """
    Verifies the HMAC-SHA256 signature of an incoming BipBip webhook.

    Args:
        secret:           HMAC secret provided by BipBip during onboarding.
        timestamp:        Value of the X-Bipbip-Timestamp header (Unix seconds as string).
        raw_body:         Raw request body bytes BEFORE any json.loads() call.
        signature:        Value of the X-Bipbip-Signature-256 header (e.g. "sha256=abc123...").
        max_skew_seconds: Maximum allowed clock skew in seconds (default: 300).

    Returns:
        True if the signature is valid and the timestamp is within the skew limit.
    """
    # Step 1: Validate timestamp to prevent replay attacks.
    # Reject requests where the clock skew exceeds max_skew_seconds.
    now = int(time.time())
    try:
        ts = int(timestamp)
    except (ValueError, TypeError):
        return False
    if abs(now - ts) > max_skew_seconds:
        return False

    # Step 2: Build the signed message exactly as BipBip does:
    #   message = "{timestamp}.{rawBody}"
    # IMPORTANT: raw_body must be the original bytes received over the wire.
    # Do NOT re-serialize a parsed JSON object — any whitespace/key-order
    # difference will produce a different signature.
    message = f"{timestamp}.{raw_body.decode('utf-8')}".encode('utf-8')

    # Step 3: Compute HMAC-SHA256 with the shared secret.
    # Both key and message are treated as UTF-8 encoded bytes.
    computed_hex = hmac.new(
        secret.encode('utf-8'),
        message,
        hashlib.sha256,
    ).hexdigest()  # hexdigest() returns lowercase hex — matches BipBip's format

    # Step 4: Prepend the "sha256=" prefix to match the header value format.
    expected = f"sha256={computed_hex}"

    # Step 5: Use a timing-safe comparison to prevent timing-oracle attacks.
    # hmac.compare_digest() is constant-time and accepts str or bytes.
    return hmac.compare_digest(expected, signature)


# ── Flask integration example ────────────────────────────────────────────────
# In your Flask app, access the raw body via request.get_data() (not request.json)
# so that the bytes are available for signature verification before deserialization.
#
# @app.route('/v1/order/<remote_id>', methods=['POST'])
# def receive_order(remote_id):
#     secret    = os.environ['BIPBIP_HMAC_SECRET']
#     timestamp = request.headers.get('X-Bipbip-Timestamp', '')
#     signature = request.headers.get('X-Bipbip-Signature-256', '')
#     raw_body  = request.get_data()  # bytes — no JSON parsing yet
#
#     if not verify_bipbip_signature(secret, timestamp, raw_body, signature):
#         return jsonify({'error': 'Invalid signature'}), 401
#
#     order = request.json  # safe to parse after verification
#     remote_order_id = your_internal_id_generator(order)
#     return jsonify({'remoteOrderId': remote_order_id}), 200

// HMAC-SHA256 webhook signature verification — C# / .NET 6+
// Verify that the webhook payload from BipBip is authentic before processing it.
// Uses only System.Security.Cryptography (built into .NET). No NuGet packages required.

using System;
using System.Security.Cryptography;
using System.Text;

/// <summary>
/// Utilities for verifying BipBip webhook signatures.
/// </summary>
public static class BipBipWebhookVerifier
{
    /// <summary>
    /// Verifies the HMAC-SHA256 signature of an incoming BipBip webhook.
    /// </summary>
    /// <param name="secret">HMAC secret provided by BipBip during onboarding.</param>
    /// <param name="timestamp">Value of the X-Bipbip-Timestamp header (Unix seconds as string).</param>
    /// <param name="rawBody">Raw request body string BEFORE any deserialization.</param>
    /// <param name="signature">Value of the X-Bipbip-Signature-256 header (e.g. "sha256=abc123...").</param>
    /// <param name="maxSkewSeconds">Maximum allowed clock skew in seconds (default: 300).</param>
    /// <returns>True if the signature is valid and the timestamp is within the skew limit.</returns>
    public static bool VerifySignature(
        string secret,
        string timestamp,
        string rawBody,
        string signature,
        int maxSkewSeconds = 300)
    {
        // Step 1: Validate timestamp to prevent replay attacks.
        // Reject requests where the clock skew exceeds maxSkewSeconds.
        if (!long.TryParse(timestamp, out long ts))
            return false;

        long now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
        if (Math.Abs(now - ts) > maxSkewSeconds)
            return false;

        // Step 2: Build the signed message exactly as BipBip does:
        //   message = "{timestamp}.{rawBody}"
        // IMPORTANT: rawBody must be the original string received over the wire.
        // Do NOT re-serialize a deserialized object — any whitespace/key-order
        // difference will produce a different signature.
        string message = $"{timestamp}.{rawBody}";

        // Step 3: Compute HMAC-SHA256 with the shared secret.
        // Both key and message are UTF-8 encoded bytes.
        byte[] keyBytes     = Encoding.UTF8.GetBytes(secret);
        byte[] messageBytes = Encoding.UTF8.GetBytes(message);

        using var hmac = new HMACSHA256(keyBytes);
        byte[] hashBytes = hmac.ComputeHash(messageBytes);

        // Step 4: Convert hash to lowercase hex and prepend the "sha256=" prefix.
        string computedHex = BitConverter.ToString(hashBytes)
            .Replace("-", string.Empty)
            .ToLowerInvariant();
        string expected = $"sha256={computedHex}";

        // Step 5: Use a timing-safe comparison to prevent timing-oracle attacks.
        // CryptographicOperations.FixedTimeEquals() compares byte arrays in constant time.
        byte[] expectedBytes  = Encoding.UTF8.GetBytes(expected);
        byte[] receivedBytes  = Encoding.UTF8.GetBytes(signature);

        return CryptographicOperations.FixedTimeEquals(expectedBytes, receivedBytes);
    }
}

// ── ASP.NET Core integration example ────────────────────────────────────────
// Read the raw body string from the request stream BEFORE binding to a model.
// Use [FromBody] with a string or read Request.Body manually.
//
// [HttpPost("/v1/order/{remoteId}")]
// public async Task<IActionResult> ReceiveOrder(
//     string remoteId,
//     [FromHeader(Name = "X-Bipbip-Timestamp")] string timestamp,
//     [FromHeader(Name = "X-Bipbip-Signature-256")] string signature)
// {
//     string secret  = _config["BipBip:HmacSecret"]!;
//     string rawBody = await new StreamReader(Request.Body).ReadToEndAsync();
//
//     if (!BipBipWebhookVerifier.VerifySignature(secret, timestamp, rawBody, signature))
//         return Unauthorized();
//
//     var order = JsonSerializer.Deserialize<OrderPayload>(rawBody);
//     string remoteOrderId = _orderService.CreateOrder(order!);
//     return Ok(new { remoteOrderId });
// }
//
// NOTE: To enable raw body reading in ASP.NET Core you may need to call
// Request.EnableBuffering() in a middleware before the controller executes.

<?php
/**
 * HMAC-SHA256 webhook signature verification — PHP 8.0+
 * Verify that the webhook payload from BipBip is authentic before processing it.
 * Uses only PHP built-in functions (hash_hmac, hash_equals). No Composer packages required.
 */

/**
 * Verifies the HMAC-SHA256 signature of an incoming BipBip webhook.
 *
 * @param string $secret          HMAC secret provided by BipBip during onboarding.
 * @param string $timestamp       Value of the X-Bipbip-Timestamp header (Unix seconds as string).
 * @param string $rawBody         Raw request body string BEFORE any json_decode() call.
 * @param string $signature       Value of the X-Bipbip-Signature-256 header (e.g. "sha256=abc123...").
 * @param int    $maxSkewSeconds  Maximum allowed clock skew in seconds (default: 300).
 * @return bool True if the signature is valid and the timestamp is within the skew limit.
 */
function verifyBipBipSignature(
    string $secret,
    string $timestamp,
    string $rawBody,
    string $signature,
    int $maxSkewSeconds = 300
): bool {
    // Step 1: Validate timestamp to prevent replay attacks.
    // Reject requests where the clock skew exceeds $maxSkewSeconds.
    $now = time();
    $ts  = (int) $timestamp;
    if (abs($now - $ts) > $maxSkewSeconds) {
        return false;
    }

    // Step 2: Build the signed message exactly as BipBip does:
    //   message = "{timestamp}.{rawBody}"
    // IMPORTANT: $rawBody must be the original string received over the wire.
    // Do NOT re-serialize a json_decode result — any whitespace/key-order
    // difference will produce a different signature.
    $message = "{$timestamp}.{$rawBody}";

    // Step 3: Compute HMAC-SHA256 with the shared secret.
    // hash_hmac() returns a lowercase hex string by default — matches BipBip's format.
    $computedHex = hash_hmac('sha256', $message, $secret);

    // Step 4: Prepend the "sha256=" prefix to match the header value format.
    $expected = "sha256={$computedHex}";

    // Step 5: Use a timing-safe comparison to prevent timing-oracle attacks.
    // hash_equals() is constant-time and is the recommended PHP function for this purpose.
    return hash_equals($expected, $signature);
}


// ── PHP / Laravel / Slim integration example ─────────────────────────────────
// Read the raw input BEFORE calling json_decode so that the original bytes
// are available for signature verification.
//
// // Plain PHP (no framework):
// $secret    = getenv('BIPBIP_HMAC_SECRET');
// $timestamp = $_SERVER['HTTP_X_BIPBIP_TIMESTAMP'] ?? '';
// $signature = $_SERVER['HTTP_X_BIPBIP_SIGNATURE_256'] ?? '';
// $rawBody   = file_get_contents('php://input'); // raw bytes — no JSON parsing yet
//
// if (!verifyBipBipSignature($secret, $timestamp, $rawBody, $signature)) {
//     http_response_code(401);
//     echo json_encode(['error' => 'Invalid signature']);
//     exit;
// }
//
// $order = json_decode($rawBody, true);  // safe to parse after verification
// $remoteOrderId = generateYourInternalOrderId($order);
// echo json_encode(['remoteOrderId' => $remoteOrderId]);

Mi firma no verifica

Síntoma: tu código computa el HMAC pero la firma calculada nunca coincide con X-Bipbip-Signature-256.

Causa más probable: estás firmando el JSON re-serializado en vez del raw body tal como llegó por el wire.

Cómo arreglarlo:

1. Verificá que captures los bytes crudos del body antes de cualquier llamada a JSON.parse(), json_decode() o equivalente.
2. Confirmá que el mensaje firmado sea exactamente "{timestamp}.{rawBody}" — el timestamp proviene del header, no de tu reloj local.
3. Confirmá que usás comparación en tiempo constante (ver Errores comunes).
4. Si persiste, logueá el mensaje exacto que estás firmando y comparalo byte a byte.

Recibo el webhook dos veces

Síntoma: tu POS crea la misma orden dos veces o recibe dos webhooks para el mismo evento.

Causa: BipBip entrega webhooks con garantía at-least-once. Si tu endpoint tarda demasiado en responder o hay un error de red, BipBip reintenta el envío. Eso es comportamiento esperado, no un bug.

Cómo arreglarlo: implementá deduplicación usando el header X-Bipbip-Delivery-Id. Este header es un UUID único por lote de intentos — si ya procesaste ese ID, devolvé HTTP 200 inmediatamente sin reprocesar.

// Example: deduplicación con X-Bipbip-Delivery-Id
const processed = new Set();

app.post('/v1/order/:remoteId', async (req, res) => {
  const deliveryId = req.headers['x-bipbip-delivery-id'];

  if (processed.has(deliveryId)) {
    return res.status(200).json({ remoteOrderId: yourStore.getByDeliveryId(deliveryId) });
  }

  // ... verificar HMAC, procesar orden ...
  processed.add(deliveryId);
  res.status(200).json({ remoteOrderId });
});

BipBip sigue reintentando después de mi 200

Síntoma: tu endpoint devuelve HTTP 200 pero BipBip sigue enviando el mismo webhook.

Causa: devolver HTTP 200 sin un remoteOrderId válido se trata como delivery fallido. BipBip necesita ese valor para componer la URL de los webhooks de cancelación futuros.

Cómo arreglarlo: asegurate de que tu response body sea un JSON válido con remoteOrderId no nulo y no vacío:

// Correcto — BipBip marca el delivery como exitoso
{ "remoteOrderId": "POS-INTERNAL-12345" }

// Incorrecto — BipBip trata esto como delivery fallido y reintenta
{}
{ "remoteOrderId": null }
{ "remoteOrderId": "" }

No recibo ningún webhook

Síntoma: BipBip confirma que despachó el webhook pero tu servidor no recibió nada.

Checklist:

1. URL públicamente accesible: la base URL registrada debe ser accesible desde internet. Probala con curl -X POST https://tu-servidor.com/v1/order/test desde una red externa. Las URLs localhost o VPN privada no funcionan sin tunelado (ej: ngrok).
2. Firewall y allowlist: si tu servidor tiene reglas de firewall de entrada, asegurate de permitir tráfico HTTPS desde los rangos de IP de BipBip (consultá el rango exacto al equipo).
3. Inspección de headers: si el request llega pero no lo procesás, logueá todos los headers de entrada. Verificá que X-Bipbip-Signature-256 y X-Bipbip-Timestamp estén presentes.
4. Estado en BackOffice: pedile al equipo BipBip que verifique si el delivery está Pending, Delivered o Failed.