Quickstart

Prerequisites

Before getting started, the BipBip team provides the following configuration items. You need all of them before writing your first line of code:

• 1
  HMAC Secret — shared key for verifying webhook authenticity (one per account)
• 2
  API Key (X-Bipbip-Api-Key) — authentication header for calling the REST API
• 3
  remoteId — your store identifier, defined by you (e.g. POS_TGU_001). One per registered store.
• 4
  Registered base URL — the base URL of your POS where BipBip will send webhooks (must be publicly accessible)

The 4 steps

1. 1

   Implement the webhook endpoint

   BipBip will send POST {yourBaseUrl}/v1/order/{remoteId} each time a new order arrives for your store. Your endpoint must:

   • Capture the raw body before parsing the JSON
   • Verify the HMAC signature (see HMAC Verification)
   • Return HTTP 200 with a JSON body that includes remoteOrderId
   • Respond within 30 seconds (BipBip treats any slow response as a failure)
   remoteOrderId is required

   Returning HTTP 200 without a valid remoteOrderId in the body is treated as a failed delivery and BipBip will retry. See BipBip keeps retrying.
2. 2

   Verify the HMAC signature

   Every request from BipBip includes the header X-Bipbip-Signature-256 with an HMAC-SHA256 signature. Verifying the signature guarantees that the request originates from BipBip and was not modified in transit. See the HMAC Verification section for code samples.

3. 3

   Respond with your remoteOrderId

   Once the signature is verified and the order is created in your POS, return HTTP 200 with:

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

   This value is your POS's internal identifier for this order. BipBip stores it and will include it in all subsequent cancellation webhooks so you can correlate them.

4. 4

   Accept the order by calling the REST API

   After receiving the webhook and responding with 200, you can formally accept the order by calling POST /api/v1/Orders/{orderKey}/accept. This confirms that your POS is ready to prepare the order.

   This step is optional if your store has auto-accept enabled — in that case BipBip accepts the order automatically upon receiving your 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 };

   REST API rate limits

   The API is limited to 100 requests per minute (fixed window) and 1,000 requests per hour (sliding window), partitioned by API Key. If you exceed the limit you receive HTTP 429 — implement exponential backoff with jitter in your client.

Sandbox — coming soon

The algorithm

BipBip signs each request using the following formula:

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

The relevant headers in each request are:

• X-Bipbip-Timestamp — Unix timestamp in seconds (integer as string)
• X-Bipbip-Signature-256 — the signature in sha256=<hex> format
• X-Bipbip-Delivery-Id — unique UUID per delivery batch (use for deduplication)
• X-Bipbip-Event-Type — event type. Possible values: order.created, order.cancelled, order.driver_assigned, order.delivered

Common pitfalls (footguns)

These three mistakes account for 90% of cases where the signature does not verify. Review them before looking for another problem.

Code samples

Pick your language. All samples use only the standard library — no external dependencies required.

// 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]);

My signature doesn't verify

Symptom: your code computes the HMAC but the calculated signature never matches X-Bipbip-Signature-256.

Most likely cause: you are signing the re-serialized JSON instead of the raw body as it arrived over the wire.

How to fix:

1. Verify that you capture the raw bytes of the body before any call to JSON.parse(), json_decode() or equivalent.
2. Confirm that the signed message is exactly "{timestamp}.{rawBody}" — the timestamp comes from the header, not your local clock.
3. Confirm that you are using constant-time comparison (see Common pitfalls).
4. If the problem persists, log the exact message you are signing and compare it byte by byte.

I'm receiving the webhook twice

Symptom: your POS creates the same order twice, or receives two webhooks for the same event.

Cause: BipBip delivers webhooks with at-least-once guarantee. If your endpoint takes too long to respond or a network error occurs, BipBip retries the delivery. This is expected behavior, not a bug.

How to fix: implement deduplication using the X-Bipbip-Delivery-Id header. This header is a unique UUID per delivery batch — if you have already processed that ID, return HTTP 200 immediately without reprocessing.

// 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 keeps retrying after my 200

Symptom: your endpoint returns HTTP 200 but BipBip keeps sending the same webhook.

Cause: returning HTTP 200 without a valid remoteOrderId is treated as a failed delivery. BipBip needs that value to compose the URL for future cancellation webhooks.

How to fix: ensure your response body is valid JSON with a non-null, non-empty remoteOrderId:

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

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

I'm not receiving any webhooks

Symptom: BipBip confirms it dispatched the webhook but your server received nothing.

Checklist:

1. Publicly accessible URL: the registered base URL must be reachable from the internet. Test it with curl -X POST https://your-server.com/v1/order/test from an external network. localhost or private VPN URLs do not work without tunneling (e.g. ngrok).
2. Firewall and allowlist: if your server has inbound firewall rules, make sure to allow HTTPS traffic from BipBip's IP ranges (ask the team for the exact range).
3. Header inspection: if the request arrives but is not processed, log all incoming headers. Verify that X-Bipbip-Signature-256 and X-Bipbip-Timestamp are present.
4. BackOffice status: ask the BipBip team to verify whether the delivery is Pending, Delivered or Failed.