Webhook

Receive n1co business events on your webhook hotspot

Listen for events from your n1co business account at your webhook connection point so your integration can trigger automatic reactions as events occur in your account.

Why use webhooks

When creating integrations with n1co Business, you may want your applications to receive events as they occur in your account, so that your back-end systems can execute the necessary actions.

To enable webhook events, you must register webhook connection points. After registering them, n1co Business can send real-time event data to your application's connection point when events occur. n1co Business uses HTTPS to send webhook events to your application as a JSON payload that includes an event object.

Receiving webhook events is particularly useful for listening to asynchronous events, for example, when an order is created, paid or cancelled, when the shipping status of an order is updated, etc.

Webhook configuration

To set up a webhook hotspot, you must provide a hotspot URL and generate a secret key. The connection point URL is the URL to which n1co Business will send webhook events. The secret key is a string used to sign webhook events that are sent to your application. You can use the secret key to verify that the events you receive are coming from n1co Business.

Creating a webhook connection point

To create a webhook connection point, follow these steps:

Log in to your n1co business account
In the menu on the top right, click Settings
In the Options for developers section, click Webhook
Add your webhook hotspot URL and generate a secret key, then click Save Changes.
You are done! Your webhook hotspot is ready to receive events from n1co business

Webhook events

n1co Business sends webhook events to your connection point in real time. Each webhook event includes an event object that contains information about the event that occurred in your n1co Business account. Webhook events events are sent as JSON payloads in an HTTPS POST request to your connection point.

Event object

The contract for webhook events is as follows:

{
  "orderId": "String!",
  "orderReference": "String",
  "description": "String!",
  "level": "String!",
  "type": "String!",
  "metadata": "Object"
}

The definition of the fields of the event object is as follows:

orderId: String! -> internal identifier of the order generated by the n1co system
orderReference: String -> order reference provided by the integrator
description: String! -> event description message
level: String! -> severity level of the event
type: String! -> event type
metadata: Object -> key-value object containing additional information about event

Severity Levels `level`

Info: Indicates general information or events that do not require immediate attention.
Warning: Indicates situations that may require attention or investigation, but do not represent a critical error or system failure.
Error: Indicates a system error that requires attention.

Event types `type`

Created

This event indicates that a new order has been created in n1co business.

Example:

{
  "orderId": "1057",
  "orderReference": "test-3",
  "description": "La orden fue creada",
  "metadata": null,
  "level": "Info",
  "type": "Created"
}

SuccessPayment

This event indicates that the payment of an order has been successful.

Example:

{
  "orderId": "1056",
  "orderReference": null,
  "description": "La orden fue pagada exitosamente autorización: 1715206043181",
  "metadata": {
    "PaymentId": "e6a634cb-b7d3-4ecb-8420-a80c2f3b0fed",
    "ChargeId": "a8782668-9361-4710-96ea-4b2088a5842d",
    "Status": "SUCCEEDED",
    "AuthorizationCode": "1715206043181",
    "SequentialNumber": "N/A",
    "AccountId": "hugoapp.h4b",
    "PaymentProcessor": "sandbox",
    "PaymentProcessorReference": "N/A",
    "TransactionDate": "2024-05-08T22:07:23.2092992Z",
    "PaidAmount": "1.00",
    "BuyerName": "Tim Apple",
    "BuyerPhone": "+1 408-996-1010",
    "BuyerEmail": "tim@apple.com",
    "CheckoutNote": "N/A",
    "OrderReference": "",
    "OrderTotalDetails": {
      "subtotal": "1.0000",
      "shippingAmount": "0.0000",
      "discountAmount": "0",
      "surchargeAmount": "0",
      "total": "1.00"
    }
  },
  "level": "Info",
  "type": "SuccessPayment"
}

Cancelled

This event indicates that an order has been cancelled.

Example:

{
  "orderId": "32395",
  "orderReference": null,
  "description": "La orden fue cancelada, motivo: some reason",
  "metadata": null,
  "level": "Info",
  "type": "Cancelled"
}

Finalized

This event indicates that an order has been finalized.

Ejemplo:

{
  "orderId": "32395",
  "orderReference": null,
  "description": "Se finalizó la orden.",
  "metadata": null,
  "level": "Info",
  "type": "Finalized"
}

Updated

This event indicates that the shipping status of an order in n1co business has been updated.

List of shipping statuses:

PENDING: Order pending
ACCEPTED: Order accepted
READY: Order ready
DISPATCHED: Order dispatched
ON_ITS_WAY: Order on the way
DELIVERED: Order delivered
SCHEDULED: Scheduled order
REJECTED: Order rejected

Examples:

For status change from PENDING to ACCEPTED:

{
  "orderId": "13766",
  "orderReference": null,
  "description": "Se cambió el estado del envío de Pendiente a Aceptado",
  "metadata": {
    "PreparationEtaMinutes": "15",
    "PreviousStatus": "PENDING",
    "NewStatus": "ACCEPTED"
  },
  "level": "Info",
  "type": "Updated"
}

For the change of status from ACCEPTED to READY:

{
  "orderId": "13766",
  "orderReference": null,
  "description": "Se cambió el estado del envío de Aceptado a Preparado",
  "metadata": {
    "PreviousStatus": "ACCEPTED",
    "NewStatus": "READY"
  },
  "level": "Info",
  "type": "Updated"
}

For the status change from READY to DISPATCHED:

{
  "orderId": "13766",
  "orderReference": null,
  "description": "Se cambió el estado del envío de Preparado a Despachado",
  "metadata": {
    "PreviousStatus": "READY",
    "NewStatus": "DISPATCHED"
  },
  "level": "Info",
  "type": "Updated"
}

For the status change from DISPATCHED to ON_ITS_WAY:

{
  "orderId": "13766",
  "orderReference": null,
  "description": "Se cambió el estado del envío de Despachado a En Camino",
  "metadata": {
    "PreviousStatus": "DISPATCHED",
    "NewStatus": "ON_ITS_WAY"
  },
  "level": "Info",
  "type": "Updated"
}

For the change of status from ON_ITS_WAY to DELIVERED:

{
  "orderId": "13766",
  "orderReference": null,
  "description": "Se cambió el estado del envío de En Camino a Entregado",
  "metadata": {
    "PreviousStatus": "ON_ITS_WAY",
    "NewStatus": "DELIVERED"
  },
  "level": "Info",
  "type": "Updated"
}

Deleted

This event indicates that an order has been deleted.

Example:

{
  "orderId": "32395",
  "orderReference": null,
  "description": "Se eliminó la orden",
  "metadata": null,
  "level": "Info",
  "type": "Deleted"
}

SuccessReverse

This event indicates that a payment reversal was successful.

Example:

{
  "orderId": "1056",
  "orderReference": null,
  "description": "El pago de la orden fue revertido",
  "metadata": null,
  "level": "Info",
  "type": "SuccessReverse"
}

ReverseError

This event indicates that an error occurred while attempting to reverse a payment.

Example:

{
  "orderId": "1056",
  "orderReference": null,
  "description": "La orden no pudo ser cancelada, no se pudo revertir el pago",
  "metadata": null,
  "level": "Error",
  "type": "ReverseError"
}

PaymentError

This event indicates that an error occurred while attempting to make a payment.

Example:

{
  "orderId": "1056",
  "orderReference": null,
  "description": "El pago no fue realizado: some error",
  "metadata": null,
  "level": "Error",
  "type": "PaymentError"
}

ThreeDSecureAuthSucceeded

This event indicates that the 3DS authentication was successfully completed for a specific collection and therefore you can proceed with the transaction confirmation using the authenticationId provided in the metadata of the event.

Example:

{
  "orderId": "31833",
  "orderReference": "order-integration-id",
  "description": "La autenticación 3DS ha sido completada con éxito",
  "metadata": {
      "authenticationId": "fdedee2f-5942-47ff-83a5-cb473d0e8764"
  },
  "level": "Info",
  "type": "ThreeDSecureAuthSucceeded"
}

ThreeDSecureAuthError

This event indicates that an error occurred during 3DS authentication for a specific charge. The error may be due to several reasons, such as incorrect cardholder information, technical problems with the 3DS authentication provider, or connectivity issues. Further details can be found in the reason and description attributes included in the metadata of the event.

Example:

{
  "orderId": "31833",
  "orderReference": "order-integration-id",
  "description": "Ocurrió un error en la autenticación 3DS",
  "metadata": {
      "authenticationId": "fdedee2f-5942-47ff-83a5-cb473d0e8764",
      "reason" : "Some reason",
      "description" : "Some description",
  },
  "level": "Error",
  "type": "ThreeDSecureAuthError"
}

ThreeDSecureAuthExpired

This event is an indicator that the 3DS authentication was not completed on time and the transaction cannot be completed at this time. The transaction can be reattempted later once the cardholder initiates a new authentication request.

Example:

{
  "orderId": "31833",
  "orderReference": "order-integration-id",
  "description": "La autenticación 3DS ha expirado",
  "metadata": {
      "authenticationId": "fdedee2f-5942-47ff-83a5-cb473d0e8764"
  },
  "level": "Info",
  "type": "ThreeDSecureAuthExpired"
}

ThreeDSecureAuthFailed

This event indicates that there was a technical failure that prevented 3DS authentication from completing successfully for a specific request. The failure may be due to problems with the 3DS authentication provider, integration issues, or server-side issues. Further details can be found in the reason and description attributes included in the metadata of the event.

Example:

{
  "orderId": "31833",
  "orderReference": "order-integration-id",
  "description": "Ocurrió un fallo en la autenticación 3DS",
  "metadata": {
      "authenticationId": "fdedee2f-5942-47ff-83a5-cb473d0e8764",
      "reason" : "Some reason",
      "description" : "Some description",
  },
  "level": "Error",
  "type": "ThreeDSecureAuthFailed"
}

Verification of webhook events

To verify that the webhook events you receive are coming from n1co buiness, you can use the secret key that you generated when you set up your webhook connection point. To verify a webhook event, follow these steps:

Extract the value of the X-H4B-Hmac-Sha256 header from the HTTP POST request containing the webhook event.
Calculate the HMAC SHA-256 of the HTTP POST request body using the secret key generated when you set up your webhook.

Example of webhook event verification

Node.js

app.post("/webhook", (req, res) => {
  //Llave secreta configurada en el administrador de n1co Business
  const API_SECRET = process.env.API_SECRET;

  //Extraer el valor del header X-H4B-Hmac-Sha256'
  const hmacHeader = req.get("X-H4B-Hmac-Sha256");

  const content = /* body del request como strings */ req.body;

  //Generar el hash
  const hash = crypto
    .createHash("sha256", API_SECRET)
    .update(content, "utf8", "hex")
    .digest("base64");

  if (hash === hmacHeader) {
    console.log("Notification Request from n1co Business received", body);
    res.sendStatus(200);
  } else {
    console.log("Could not validate signature", hash);
    res.sendStatus(400);
  }
});

Python

import hashlib
import hmac
from flask import Flask, request, abort

app = Flask(__name__)

@app.route("/webhook", methods=['POST'])
def webhook():
    # Llave secreta configurada en el administrador de n1co Business
    API_SECRET = os.environ.get('API_SECRET')

    # Extraer el valor del header 'X-H4B-Hmac-Sha256'
    hmac_header = request.headers.get('X-H4B-Hmac-Sha256')

    # body del request como strings
    content = request.data.decode('utf-8')

    # Generar el hash
    hash = hmac.new(API_SECRET.encode('utf-8'), content.encode('utf-8'), hashlib.sha256).hexdigest()

    if hmac.compare_digest(hash, hmac_header):
        print("Notification Request from n1co Business received", content)
        return '', 200
    else:
        print("Could not validate signature", hash)
        abort(400)

if __name__ == '__main__':
    app.run()

PHP

<?php

// Llave secreta configurada en el administrador de n1co Business
const API_SECRET = getenv("API_SECRET");

// Extraer el valor del header X-H4B-Hmac-Sha256'
$hmacHeader = $_SERVER["HTTP_X_H4B_HMAC_SHA256"];

// Body del request como strings
$content = file_get_contents("php://input");

// Generar el hash
$hash = hash_hmac("sha256", $content, API_SECRET);

if ($hash === $hmacHeader) {
  echo "Notification Request from n1co Business received";
  http_response_code(200);
} else {
  echo "Could not validate signature";
  http_response_code(400);
}

?>

Why use webhooks​

Webhook configuration​

Creating a webhook connection point​

Webhook events​

Event object​

Severity Levels level​

Event types type​

Created​

SuccessPayment​

Cancelled​

Finalized​

Updated​

Deleted​

SuccessReverse​

ReverseError​

PaymentError​

ThreeDSecureAuthSucceeded​

ThreeDSecureAuthError​

ThreeDSecureAuthExpired​

ThreeDSecureAuthFailed​

Verification of webhook events​

Example of webhook event verification​

Node.js​

Python​

PHP​

Why use webhooks

Webhook configuration

Creating a webhook connection point

Webhook events

Event object

Severity Levels `level`

Event types `type`

Created

SuccessPayment

Cancelled

Finalized

Updated

Deleted

SuccessReverse

ReverseError

PaymentError

ThreeDSecureAuthSucceeded

ThreeDSecureAuthError

ThreeDSecureAuthExpired

ThreeDSecureAuthFailed

Verification of webhook events

Example of webhook event verification

Node.js

Python

PHP