Webhooks

En esta sección, verás como configurar y trabajar con los webhooks para recibir notificaciones en tiempo real, relacionadas con los eventos que viste anteriormente, así tendrás visibilidad de como opera tu negocio. Para esto, tienes tres métodos distintos de autenticación para trabajar:

Métodos de autenticación

• None (sin autenticación): No se requiere verificación, cualquier solicitud puede ser procesada.
• Básica (usuario y contraseña): Se envían credenciales básicas (usuario y contraseña) para garantizar que solo solicitudes autorizadas sean aceptadas.
• Bearer token: Se utiliza un token único para validar las solicitudes, proporcionando un mayor nivel de seguridad.

Crear el Webhook para Autofacturador

En este paso, debes configurar el webhook al que se disparará el evento, definiendo el tipo de autenticación que se utilizara. A continuación verás los parámetros que se utilizaran para crear el webhook:

Parámetro	Tipo	Requerido	Detalles
url	String	Requerido	Max 255 caracteres Esta url es de tu servicio/api a la cual vamos a notificar que se facturó una venta registrada en el autofacturador. Para sandbox se permite url con http, pero para producción se requiere una url con https http://tu-dominio.com/path/to/endpoint
authentication	String	Requerido	Este parámetro te permite definir el tipo de autenticación que se utilizará al recibir las notificaciones del webhook en tu URL, si fuera necesario. Este valor queda a tu discreción configurarlo según tus necesidades, ya que recordemos que la URL que nos brindes forma parte de tu servidor. Los valores permitidos son los siguientes: "none" "basic" "bearer"
name	String	Requerido	Es requerido agregar el nombre del evento en cuestión, por ejemplo: autofacturacion.timbrado. Puede ver mas de esto en la sección de Eventos.
username	String	Opcional	Es requerido si se usa autenticación Básica Max 150 caracteres. En este campo se envía el valor usuario para la autenticación, este valor se envía en la notificación cuando un evento del webhook ocurre.
password	String	Opcional	Es requerido si se usa autenticación Básica Max 250 caracteres. En este campo se envía el valor contraseña para la autenticación, este valor se envía en la notificación cuando un evento del webhook ocurre.
token	String	Opcional	Es requerido si se usa autenticación Bearer token Max 250 caracteres. En este campo se envía el valor bearer-token para la autenticación, este valor se envía en la notificación cuando un evento del webhook ocurre.

Construcción de la URL

Importante

El método que se utiliza para crear webhooks es de tipo POST.

Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)

Endpoint: /v4/webhooks/settings

Ejemplo: https://facturaonline.com.mx/api/api/v4/webhooks/settings

Ejemplo para crear Webhook sin método de autenticación

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{ HOST }/api/v4/webhooks/settings',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "url": "http://tu-dominio.com/path/to/endpoint",
    "authentication": "none",
    "name": "autofacturacion.timbrado"
    }',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key: Tu API key',
    'F-Secret-Key: Tu Secret key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
  'method': 'POST',
  'url': '{ HOST }/v4/webhooks/settings',
  'headers': {
    'Content-Type': 'application/json',
    'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key': 'Tu API key',
    'F-Secret-Key': 'Tu Secret key'
  },
    body: JSON.stringify({
    "url": "http://tu-dominio.com/path/to/endpoint",
    "authentication": "none",
    "name": "autofacturacion.timbrado"
  })
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json

url = "{ HOST }/v4/webhooks/settings"

payload = ({
  "url": "http://tu-dominio.com/path/to/endpoint",
  "authentication": "none",
  "name": "autofacturacion.timbrado"
})
headers = {
  'Content-Type': 'application/json',
  'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
  'F-Api-Key': 'Tu API key',
  'F-Secret-Key': 'Tu Secret key'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("{ HOST }/v4/webhooks/settings")

http = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
request.body = JSON.dump({
  "url": "http://tu-dominio.com/path/to/endpoint",
  "authentication": "none",
  "name": "autofacturacion.timbrado"
})

response = http.request(request)
puts response.read_body

Ejemplo para crear Webhook con método de autenticación Básico

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{ HOST }/api/v4/webhooks/settings',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "url": "http://tu-dominio.com/path/to/endpoint",
    "authentication": "basic",
    "username": "your-username",
    "password": "your-password",
    "name": "autofacturacion.timbrado"
    }',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key: Tu API key',
    'F-Secret-Key: Tu Secret key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
  'method': 'POST',
  'url': '{ HOST }/v4/webhooks/settings',
  'headers': {
    'Content-Type': 'application/json',
    'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key': 'Tu API key',
    'F-Secret-Key': 'Tu Secret key'
  },
    body: JSON.stringify({
    "url": "http://tu-dominio.com/path/to/endpoint",
    "authentication": "basic",
    "username": "your-username",
    "password": "your-password",
    "name": "autofacturacion.timbrado"
  })
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json

url = "{ HOST }/v4/webhooks/settings"

payload = ({
  "url": "http://tu-dominio.com/path/to/endpoint",
  "authentication": "basic",
  "username": "your-username",
  "password": "your-password",
  "name": "autofacturacion.timbrado"
})
headers = {
  'Content-Type': 'application/json',
  'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
  'F-Api-Key': 'Tu API key',
  'F-Secret-Key': 'Tu Secret key'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("{ HOST }/v4/webhooks/settings")

http = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
request.body = JSON.dump({
  "url": "http://tu-dominio.com/path/to/endpoint",
  "authentication": "basic",
  "username": "your-username",
  "password": "your-password",
  "name": "autofacturacion.timbrado"
})

response = http.request(request)
puts response.read_body

Ejemplo para crear Webhook con método de autenticación Bearer token

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{ HOST }/api/v4/webhooks/settings',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "url": "http://tu-dominio.com/path/to/endpoint",
    "authentication": "bearer",
    "token": "your-token",
    "name": "autofacturacion.timbrado"
    }',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key: Tu API key',
    'F-Secret-Key: Tu Secret key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
  'method': 'POST',
  'url': '{ HOST }/v4/webhooks/settings',
  'headers': {
    'Content-Type': 'application/json',
    'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key': 'Tu API key',
    'F-Secret-Key': 'Tu Secret key'
  },
    body: JSON.stringify({
    "url": "http://tu-dominio.com/path/to/endpoint",
    "authentication": "bearer",
    "token": "your-token",
    "name": "autofacturacion.timbrado"
  })
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json

url = "{ HOST }/v4/webhooks/settings"

payload = ({
  "url": "http://tu-dominio.com/path/to/endpoint",
  "authentication": "bearer",
  "token": "your-token",
  "name": "autofacturacion.timbrado"
})
headers = {
  'Content-Type': 'application/json',
  'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
  'F-Api-Key': 'Tu API key',
  'F-Secret-Key': 'Tu Secret key'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("{ HOST }/v4/webhooks/settings")

http = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
request.body = JSON.dump({
  "url": "http://tu-dominio.com/path/to/endpoint",
  "authentication": "bearer",
  "token": "your-token",
  "name": "autofacturacion.timbrado"
})

response = http.request(request)
puts response.read_body

Respuesta

Ejemplo de respuesta exitosa

{
    "name": "autofacturacion.timbrado",
    "url": "http://tu-dominio.com/path/to/endpoint",
    "uuid": "7318a279-22c9-4894-b5bf-b37ebfb140e1",
    "authentication": "none",
    "status": "pending",
    "updated_at": "2025-01-20 10:28:00",
    "created_at": "2025-01-20 10:28:00"
}

Ejemplo de respuesta de error

{
    "errors": "El campo authentication es requerido"
}

Validar el webhook

Una vez creado el webhook, se quedará en estatus “pending” y este se debe validar para que inicie el envío de peticiones cuando se emitan las facturas en el autofacturador. Si la validación falla se pondrá en estatus “error” y si pasa se pondrá en estatus “validated”.

Parámetro	Tipo	Requerido	Detalles
webhook-uuid	String	Requerido	cuando creas el webhook te retorna un uuid el cual deberás usar para realizar la validación.

Construcción de la URL

Importante

El método que se utiliza para validar webhooks es de tipo GET.

Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)

Endpoint: v4/webhooks/validate/[webhook-uuid]

Ejemplo: https://facturaonline.com.mx/api/api/v4/webhooks/validate/[webhook-uuid]

Ejemplo para validar webhook

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{ HOST }/api/v4/webhooks/validate/[webhook-uuid]',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key: Tu API key',
    'F-Secret-Key: Tu Secret key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
  'method': 'GET',
  'url': '{ HOST }/v4/webhooks/validate/[webhook-uuid]',
  'headers': {
    'Content-Type': 'application/json',
    'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key': 'Tu API key',
    'F-Secret-Key': 'Tu Secret key'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json

url = "{ HOST }/v4/webhooks/validate/[webhook-uuid]"

payload = ""
headers = {
  'Content-Type': 'application/json',
  'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
  'F-Api-Key': 'Tu API key',
  'F-Secret-Key': 'Tu Secret key'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("{ HOST }/v4/webhooks/validate/[webhook-uuid]")

http = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"

response = http.request(request)
puts response.read_body

Respuesta

Para confirmar que ya has recibido una notificación de un de nuestros webhooks correctamente, tu servidor debe regresar un código 200 de HTTP.

Ejemplo de respuesta exitosa

{
    "status": "validated"
}

Ejemplo de respuesta de error

 {
    "status": "El UUID no es valido"
 }

Envío de notificaciones

Después de validar el Webhook, enviaremos notificaciones cada que se emita una factura. El evento es "autofacturacion timbrado". Si el endpoint responde un http Code diferente a 200, se intentará de nuevo cada 10 minutos hasta un máximo de 5 intentos. Si después de esos intentos sigue marcando el http Code diferente a 200, marcaremos el endpoint como error y se dejará de enviar notificaciones y se deberá hacer nuevamente el proceso de validación.

Ejemplo de respuesta exitosa sin método de autenticación

    Headers
    Origin: Depende del ambiente, puede ser producción o sandbox.
    Payload
{
  "event": "autofacturacion.timbrado",
  "uuid": "uuid de la factura",
  "folio": "folio de la venta registrada en el autofacturador",
  "uid": "uid de la factura",
  "xml": "xml de la factura"
}

Ejemplo de respuesta exitosa con método de autenticación Básico

    Headers
    Authorization: Basic base64(username:password)
    Origin: Depende del ambiente, puede ser producción o sandbox.
    Payload
{
  "event": "autofacturacion.timbrado",
  "uuid": "uuid de la factura",
  "folio": "folio de la venta registrada en el autofacturador",
  "uid": "uid de la factura",
  "xml": "xml de la factura"
}

Ejemplo de respuesta exitosa con método de autenticación Bearer

    Headers
    Authorization: Token your-token
    Origin: Depende del ambiente, puede ser producción o sandbox.
    Payload
{
  "event": "autofacturacion.timbrado",
  "uuid": "uuid de la factura",
  "folio": "folio de la venta registrada en el autofacturador",
  "uid": "uid de la factura",
  "xml": "xml de la factura"
}

Actualizar Webhook

En caso de requerir actualizar el webhook se deberá llamar al método update y posteriormente llamar al método "validate".

Parámetro	Tipo	Requerido	Detalles
webhook-uuid	String	Requerido	Cuando creas el webhook te proporciona un uuid que tiene asignado, este es necesario para actualizarlo.
url	String	Requerido	Si requerimos cambiar la url del webhook es necesario enviar este parámetro.
authentication	String	Opcional	Si necesitamos cambiar el tipo de autenticación de nuestro webhook podemos hacerlo con este parámetro.
name	String	Requerido	Es requerido en caso de querer cambiar este dato del webhook.
username	String	Opcional	Es necesario enviarlo en caso de utilizar autenticación básica al actualizar el webhook.
password	String	Opcional	Es necesario enviarlo en caso de utilizar autenticación básica al actualizar el webhook.
token	String	Opcional	Es necesario enviarlo en caso de utilizar autenticación bearer al actualizar el webhook.

Construcción de la URL

Importante

El método que se utiliza para validar webhooks es de tipo POST.

Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)

Endpoint: v4/webhooks/settings/[webhook-uuid]

Ejemplo: https://facturaonline.com.mx/api/api/v4/webhooks/settings/[webhook-uuid]

Ejemplo para actualizar webhook

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{ HOST }/api/v4/webhooks/settings/[webhook-uuid]',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "url": "http://tu-dominio.com/path/to/endpoint",
    "authentication": "basic",
    "username": "your-username",
    "password": "your-password",
    "name": "autofacturacion.timbrado"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key: Tu API key',
    'F-Secret-Key: Tu Secret key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
  'method': 'POST',
  'url': '{ HOST }/v4/webhooks/settings/[webhook-uuid]',
  'headers': {
    'Content-Type': 'application/json',
    'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key': 'Tu API key',
    'F-Secret-Key': 'Tu Secret key'
  },
    body: JSON.stringify({
    "url": "http://tu-dominio.com/path/to/endpoint",
    "authentication": "basic",
    "username": "your-username",
    "password": "your-password",
    "name": "autofacturacion.timbrado"
  })
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json

url = "{ HOST }/v4/webhooks/settings/[webhook-uuid]"

payload = ({
  "url": "http://tu-dominio.com/path/to/endpoint",
  "authentication": "basic",
  "username": "your-username",
  "password": "your-password",
  "name": "autofacturacion.timbrado"
})
headers = {
  'Content-Type': 'application/json',
  'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
  'F-Api-Key': 'Tu API key',
  'F-Secret-Key': 'Tu Secret key'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("{ HOST }/v4/webhooks/settings/[webhook-uuid]")

http = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"
request.body = JSON.dump({
  "url": "http://tu-dominio.com/path/to/endpoint",
  "authentication": "basic",
  "username": "your-username",
  "password": "your-password",
  "name": "autofacturacion.timbrado"
})

response = http.request(request)
puts response.read_body

Respuesta

Ejemplo de respuesta exitosa

{
    "uuid": "bb92dc04-47ba-4d4c-ab57-06c1009d6342",
    "url": "https://sandbox.factura.com/webhook/test03",
    "status": "pending",
    "created_at": "2024-10-18 18:11:35",
    "updated_at": "2025-01-20 10:27:04",
    "authentication": "basic",
    "username": "user",
    "password": "pass",
    "name": "autofacturacion.timbrado"
}

Ejemplo de respuesta de error

 {
    "status": "El UUID no es valido"
 }

Consultar Webhook

Aquí te mostramos de que forma consultar un webhook.

Construcción de la URL

Importante

El método que se utiliza para validar webhooks es de tipo GET.

Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)

Endpoint: v4/webhooks

Ejemplo: https://facturaonline.com.mx/api/api/v4/webhooks

Tip

Para probar el código de ejemplo es necesario que reemplaces el texto Ingresa API KEY por el API KEY de tu cuenta, e Ingresa SECRET KEY por el SECRET KEY correspondiente.

Ejemplo para consultar webhook

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{ HOST }/api/v4/webhooks',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key: Tu API key',
    'F-Secret-Key: Tu Secret key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
  'method': 'GET',
  'url': '{ HOST }/v4/webhooks',
  'headers': {
    'Content-Type': 'application/json',
    'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key': 'Tu API key',
    'F-Secret-Key': 'Tu Secret key'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json

url = "{ HOST }/v4/webhooks"

payload = ""
headers = {
  'Content-Type': 'application/json',
  'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
  'F-Api-Key': 'Tu API key',
  'F-Secret-Key': 'Tu Secret key'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("{ HOST }/v4/webhooks")

http = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"

response = http.request(request)
puts response.read_body

Respuesta

Ejemplo de respuesta exitosa

[
    {
        "uuid": "92269e63-57d1-4ddd-b5d4-aced7815ccc9",
        "url": "http://tu-dominio.com/path/to/endpoint",
        "status": "error",
        "created_at": "2024-10-18 16:45:07",
        "updated_at": "2024-12-09 14:16:49",
        "authentication": "basic",
        "username": "user",
        "password": "pass",
        "name": null
    },
    {
        "uuid": "bb92dc04-47ba-4d4c-ab57-06c1009d6342",
        "url": "http://tu-dominio.com/path/to/endpoint",
        "status": "pending",
        "created_at": "2024-10-18 18:11:35",
        "updated_at": "2025-01-20 10:27:04",
        "authentication": "basic",
        "username": "user",
        "password": "pass",
        "name": "autofacturacion.timbrado"
    },
]    

Ejemplo de respuesta de error

 {
    "status": "El UUID no es valido"
 }

Consultar un Webhook en especifico

También se puede consultar un solo webhook en específico, así es como se hace.

Construcción de la URL

Importante

El método que se utiliza para validar webhooks es de tipo GET.

Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)

Endpoint: v4/webhooks/[uuid]

Ejemplo: https://facturaonline.com.mx/api/api/v4/webhooks/[uuid]

Tip

Para probar el código de ejemplo es necesario que reemplaces el texto Ingresa API KEY por el API KEY de tu cuenta, e Ingresa SECRET KEY por el SECRET KEY correspondiente. También cambiar uuid por el uuid de la factura.

Ejemplo para consultar un webhook en especifico

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{ HOST }/api/v4/webhooks/[uuid]',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key: Tu API key',
    'F-Secret-Key: Tu Secret key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
  'method': 'GET',
  'url': '{ HOST }/v4/webhooks/[uuid]',
  'headers': {
    'Content-Type': 'application/json',
    'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key': 'Tu API key',
    'F-Secret-Key': 'Tu Secret key'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json

url = "{ HOST }/v4/webhooks/[uuid]"

payload = ""
headers = {
  'Content-Type': 'application/json',
  'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
  'F-Api-Key': 'Tu API key',
  'F-Secret-Key': 'Tu Secret key'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("{ HOST }/v4/webhooks/[uuid]")

http = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"

response = http.request(request)
puts response.read_body

Respuesta

Ejemplo de respuesta exitosa

{
    "uuid": "bb92dc04-47ba-4d4c-ab57-06c1009d6342",
    "url": "https://sandbox.factura.com/webhook/test03",
    "status": "pending",
    "created_at": "2024-10-18 18:11:35",
    "updated_at": "2025-01-20 10:27:04",
    "authentication": "basic",
    "username": "user",
    "password": "pass",
    "name": "autofacturacion.timbrado"
}

Ejemplo de respuesta de error

 {
    "El webhook no existe"
 }

Consultar log de las peticiones

Puedes consultar el log de las peticiones para realizar seguimientos, así identificar eventos y errores.

Construcción de la URL

Importante

El método que se utiliza para validar webhooks es de tipo GET.

Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)

Endpoint: v4/webhooks/logs

Ejemplo: https://facturaonline.com.mx/api/api/v4/webhooks/logs

Tip

Para probar el código de ejemplo es necesario que reemplaces el texto Ingresa API KEY por el API KEY de tu cuenta, e Ingresa SECRET KEY por el SECRET KEY correspondiente.

Ejemplo para consultar el log

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{ HOST }/api/v4/webhooks/logs',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key: Tu API key',
    'F-Secret-Key: Tu Secret key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
  'method': 'GET',
  'url': '{ HOST }/v4/webhooks/logs',
  'headers': {
    'Content-Type': 'application/json',
    'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key': 'Tu API key',
    'F-Secret-Key': 'Tu Secret key'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json

url = "{ HOST }/v4/webhooks/logs"

payload = ""
headers = {
  'Content-Type': 'application/json',
  'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
  'F-Api-Key': 'Tu API key',
  'F-Secret-Key': 'Tu Secret key'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("{ HOST }/v4/webhooks/logs")

http = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"

response = http.request(request)
puts response.read_body

Respuesta

Ejemplo de respuesta exitosa

{
        "uuid": "98d1613e-5267-45f3-9883-b47c6e17a558",
        "payload": "{\"event\":\"validate\",\"url\":\"http:\\/\\/tu-dominio.com\\/path/to\\/endpoint\"}",
        "response_code": 200,
        "response_body": "{\"response\":\"success\",\"message\":\"ok\"}",
        "event": "verify",
        "created_at": "2024-10-18 18:38:16",
        "updated_at": "2024-10-18 18:38:16",
        "webhook_uuid": "bb92dc04-47ba-4d4c-ab57-06c1009d6342",
        "NameWebhook": "autofacturacion.timbrado"
    },
    {
        "uuid": "c4bc8b28-cb11-46fe-86cd-face1f312aa4",
        "payload": "{\"event\":\"validate\",\"url\":\"http:\\/\\/tu-dominio.com\\/path/to\\/endpoint\"}",
        "response_code": 200,
        "response_body": "{\"response\":\"success\",\"message\":\"ok\"}",
        "event": "verify",
        "created_at": "2024-10-18 18:39:36",
        "updated_at": "2024-10-18 18:39:36",
        "webhook_uuid": "bb92dc04-47ba-4d4c-ab57-06c1009d6342",
        "NameWebhook": "autofacturacion.timbrado"
 }

Ejemplo de respuesta de error

 {
    "No hay logs"
 }

Importante

El log de webhooks se depura cada 30 días.

Consultar log de un solo webhook

También es posible consultar el log de un solo evento (webhook), aquí te explicamos como hacerlo.

Construcción de la URL

Importante

El método que se utiliza para validar webhooks es de tipo GET.

Host: https://facturaonline.com.mx/api (producción) / https://sandbox.facturaonline.com.mx/api (sandbox)

Endpoint: v4/webhooks/[webhook_uuid]/logs

Ejemplo: https://facturaonline.com.mx/api/api/v4/webhooks/[webhook_uuid]/logs

Tip

Para probar el código de ejemplo es necesario que reemplaces el texto Ingresa API KEY por el API KEY de tu cuenta, e Ingresa SECRET KEY por el SECRET KEY correspondiente. Además de cambiar [webhook_uuid] por el uuid de tu webhook.

Ejemplo para consultar el log de un webhook

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{ HOST }/api/v4/webhooks/[webhook_uuid]/logs',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'F-PLUGIN: 9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key: Tu API key',
    'F-Secret-Key: Tu Secret key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
  'method': 'GET',
  'url': '{ HOST }/v4/webhooks/[webhook_uuid]/logs',
  'headers': {
    'Content-Type': 'application/json',
    'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
    'F-Api-Key': 'Tu API key',
    'F-Secret-Key': 'Tu Secret key'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json

url = "{ HOST }/v4/webhooks/[webhook_uuid]/logs"

payload = ""
headers = {
  'Content-Type': 'application/json',
  'F-PLUGIN': '9d4095c8f7ed5785cb14c0e3b033eeb8252416ed',
  'F-Api-Key': 'Tu API key',
  'F-Secret-Key': 'Tu Secret key'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

require "uri"
require "json"
require "net/http"

url = URI("{ HOST }/v4/webhooks/[webhook_uuid]/logs")

http = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["F-PLUGIN"] = "9d4095c8f7ed5785cb14c0e3b033eeb8252416ed"
request["F-Api-Key"] = "Tu API key"
request["F-Secret-Key"] = "Tu Secret key"

response = http.request(request)
puts response.read_body

Respuesta

Ejemplo de respuesta exitosa

{
        "uuid": "98d1613e-5267-45f3-9883-b47c6e17a558",
        "payload": "{\"event\":\"validate\",\"url\":\"https:\\/\\/tu-dominio.com\\/path/to\\/endpoint\"}",
        "response_code": 200,
        "response_body": "{\"response\":\"success\",\"message\":\"ok\"}",
        "event": "verify",
        "created_at": "2024-10-18 18:38:16",
        "updated_at": "2024-10-18 18:38:16"
},

Ejemplo de respuesta de error

 {
    "El webhook no existe"
 }

Importante

El log de webhooks se depura cada 30 días.