API > Webhooks - Nuevo Webhook

Webhooks - Nuevo webhook

POST https://{entorno}.ticketbaiws.eus/webhooks/

Permite crear un webhook para notificar del cambio de estado de una factura cuando se hacen envíos asíncronos y, con el parámetro eventos, de los eventos de la factura electrónica B2B (SPFE).

Disponible en pruebas y en producción. Cada entorno tiene sus propios webhooks: créalo con api-test y el token de pruebas para recibir los avisos de las facturas de pruebas, y con api y el token de producción para las reales. Cada aviso lleva la cabecera X-TbaiWs-Environment con el entorno (test o real).

PARÁMETROS

url string obligatorio URL a la que enviar el webhook	https://...
secret string obligatorio Clave para la firma del webhook para validación del contenido. La firma se realiza mediante HMAC SHA256 y la firma se envía en base64 en el header X-Tbaiws-Hmac-Sha256	xajky22kjasy
solo_errores boolean opcional Parámetro para enviar el webhook únicamente si se producen errores o si la factura es aceptada con errores o avisos	true
activo boolean opcional Webhook activado. Permite apagar el webhook temporalmente	true
eventos array opcional Eventos que se notifican a este webhook. Por defecto ["cambio_estado"]. Ver la tabla de eventos	["cambio_estado", "spfe_envio"]

Método de cálculo de firma en PHP:
$calculated_hmac = base64_encode(hash_hmac('sha256', $request_body , $secret, true));

EVENTOS

cambio_estado
Por defecto. Resultado del envío a Hacienda (TicketBAI o Verifactu) de una factura enviada de forma asíncrona: serie, numero, fecha_emision, estado (OK / ERROR) y avisos.

spfe_envio
Factura electrónica B2B: la AEAT ha aceptado o rechazado una factura enviada a la SPFE (alta o anulación), o no se ha podido enviar porque faltan datos. Lleva serie, numero, fecha_emision, nif_cliente, tipo (alta / anulacion), estado (OK / ERROR), errores y localizador.

spfe_estado
Factura electrónica B2B: resultado de un pago, cobro, rechazo o impago comunicado con POST spfe-estados. Mismos campos que GET spfe-estados.

spfe_recibida
Factura electrónica B2B: nueva factura recibida de un proveedor a través de la SPFE. Mismos campos que GET spfe-recibidas. Se envía aunque el webhook tenga solo_errores.

Cada aviso lleva la cabecera X-TbaiWs-Topic con el nombre del evento. En los eventos spfe_* el JSON incluye además codigo_webhook, nif y evento. Con solo_errores, spfe_envio y spfe_estado solo se notifican cuando el resultado es ERROR.

POST https://{entorno}.ticketbaiws.eus/webhooks/

$ curl --request POST \
     --url https://api-test.ticketbaiws.eus/webhooks/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Token: xxx' \
     --header 'Nif: 00000014Z'
	 --data '
{
    "url": "https://www.berein.com/",
    "secret": "xajky22kjasy",
    "solo_errores" : true,
    "activo": true,
    "eventos": ["cambio_estado", "spfe_envio", "spfe_recibida"]
}'

$ composer require guzzlehttp/guzzle

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api-test.ticketbaiws.eus/webhooks/', [
  'body' => '{"url": "https://www.berein.com/","secret": "xajky22kjasy","solo_errores" : true,"activo": true,"eventos": ["cambio_estado","spfe_envio","spfe_recibida"]}',
  'headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'Token' => 'xxx',
    'Nif' => '00000014Z'
  ],
]);

echo $response->getBody();

$ python -m pip install requests

import requests

url = "https://api-test.ticketbaiws.eus/webhooks/"
payload = {
    "url": "https://www.berein.com/",
    "secret": "xajky22kjasy",
    "solo_errores" : true,
    "activo": true,
    "eventos": ["cambio_estado", "spfe_envio", "spfe_recibida"]
}

headers = {"Accept": "application/json", "Token" : "xxx", "Nif" : "00000014Z"}
response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api-test.ticketbaiws.eus/webhooks/");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Accept: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, '{"url": "https://www.berein.com/","secret": "xajky22kjasy","solo_errores" : true,"activo": true,"eventos": ["cambio_estado","spfe_envio","spfe_recibida"]}');

CURLcode ret = curl_easy_perform(hnd);

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, '{"url": "https://www.berein.com/","secret": "xajky22kjasy","solo_errores" : true,"activo": true,"eventos": ["cambio_estado","spfe_envio","spfe_recibida"]}');

Request request = new Request.Builder()
  .url("https://api-test.ticketbaiws.eus/webhooks/")
  .post(body)
  .addHeader("Accept", "application/json")
  .addHeader("Token", "xxx")
  .addHeader("Nif", "00000014Z")
  .build();
  
Response response = client.newCall(request).execute();

{ } Response JSON

HTTP/1.1 200 OK
{
    "result": "OK",
    "return": {
        "codigo": "6904a3501874e",
        "url": "https://www.berein.com/",
        "entorno": "test",
        "secret": "xajky22kjasy",
        "solo_errores": true,
        "activo": true,
        "fecha_creado": "2025-10-31T12:53:52+01:00",
        "fecha_modificado": "2025-11-03T10:16:15+01:00",
        "eventos": ["cambio_estado", "spfe_envio", "spfe_recibida"]
    },
    "msg": ""
}

Ejemplo notificación JSON

Headers:
array (
 'X-Tbaiws-Hmac-Sha256' => 'Hl+X3FT/r5yH3wsgaku46votvTpUPSLPeDNCiCj+syM=',
 'X-Tbaiws-Topic' => 'cambio_estado',
 'X-Tbaiws-Environment' => 'real',
 'X-Tbaiws-Id' => '6904a3501884e',
 'User-Agent' => 'TbaiWS Hook',
 'Content-Type' => 'application/json',
 'Content-Length' => '144',
 'Connection' => 'close'
)

Payload:
{"nif":"B123456789","serie":"5","numero":"500593135","fecha_emision":"03\\/11\\/2025","estado":"OK","avisos":"null"}

Ejemplo notificación spfe_envio (factura electrónica B2B) JSON

Headers:
 'X-Tbaiws-Topic' => 'spfe_envio'

Payload:
{"codigo_webhook":"6904a3501884e","nif":"B123456789","evento":"spfe_envio","serie":"A","numero":"2026000245","fecha_emision":"28\/10\/2026","nif_cliente":"B01000012","tipo":"alta","estado":"ERROR","errores":[{"codigo":"SPFE-CORE-39","descripcion":"Es obligatorio informar la ciudad del comprador"}],"localizador":""}

Ejemplo notificación spfe_recibida (factura electrónica B2B) JSON

Headers:
 'X-Tbaiws-Topic' => 'spfe_recibida'

Payload:
{"codigo_webhook":"6904a3501884e","nif":"B123456789","evento":"spfe_recibida","id":57,"factura":"F2026-0153","fecha_factura":"03\/11\/2026","tipo_factura":"380","copia":false,"nif_emisor":"B01000012","nombre_emisor":"Empresa de ejemplo S.L.","base":250,"cuota":52.5,"total":302.5,"vencimiento":"03\/12\/2026","estado":"pendiente","localizador":"LOCGENV1:O:NdjdSHy1PAqwlw...","fecha_descarga":"04\/11\/2026 10:05:12"}

Webhooks - Nuevo webhook

Métodos TicketBAI / Verifactu

Documento representación

Métodos específicos para BATUZ BIZKAIA

Factura electrónica B2B - SPFE (Ley Crea y Crece)

Otros métodos