Webhooks

What are webhooks?

Webhooks are HTTP notifications that Taxo sends to your application when important events occur, such as the completion of an extraction. Instead of constant polling, your application receives updates automatically.

Real-time

Receive instant notifications when documents are ready

Efficiency

Eliminates the need for constant API polling

Reliability

Automatic retry system with exponential backoff

Security

HMAC-SHA256 signature verification to authenticate events

Webhook configuration

Access dashboard

Go to Taxo Dashboard → Settings → Webhooks

Create endpoint

Click “Add Webhook” and enter your endpoint URL

Select events

Choose the types of events you want to receive:

extraction.completed - Extraction completed successfully
extraction.failed - Extraction failed
document.ready - Individual document ready for download

Configure security

Optionally, configure a secret to verify HMAC signatures

Test connection

Use the “Test Webhook” button to verify that your endpoint responds correctly

Event types

extraction.completed

Sent when an extraction completes successfully.

{
  "event": {
    "type": "extraction.completed",
    "timestamp": "2025-01-04T13:15:42.123Z",
    "version": "1.0"
  },
  "data": {
    "extractionId": "JOB20250104123456789A",
    "status": "COMPLETED",
    "completedAt": "2025-01-04T13:15:42.123Z",
    "summary": {
      "totalDocuments": 1500,
      "successfulDownloads": 1498,
      "failedDownloads": 2,
      "totalSizeBytes": 15728640
    },
    "subject": {
      "identification": "ABC010101ABC",
      "fullName": "Empresa ABC S.A. de C.V.",
      "personType": "MORAL"
    },
    "options": {
      "informationType": "INVOICE",
      "period": {
        "from": "2024-01-01",
        "to": "2024-12-31"
      },
      "direction": "RECEIVED"
    }
  }
}

extraction.failed

Sent when an extraction fails due to an unrecoverable error.

{
  "event": {
    "type": "extraction.failed",
    "timestamp": "2025-01-04T12:38:12.456Z",
    "version": "1.0"
  },
  "data": {
    "extractionId": "JOB20250104123456789A",
    "status": "FAILED",
    "failedAt": "2025-01-04T12:38:12.456Z",
    "error": {
      "code": "INVALID_CREDENTIALS",
      "message": "Las credenciales CIEC proporcionadas son incorrectas",
      "details": {
        "satResponse": "Usuario o contraseña incorrectos"
      }
    },
    "subject": {
      "identification": "ABC010101ABC"
    },
    "options": {
      "informationType": "INVOICE",
      "period": {
        "from": "2024-01-01",
        "to": "2024-12-31"
      }
    }
  }
}

document.ready

Sent for each document that is processed successfully (optional, may generate many notifications).

{
  "event": {
    "type": "document.ready",
    "timestamp": "2025-01-04T13:10:15.789Z",
    "version": "1.0"
  },
  "data": {
    "extractionId": "JOB20250104123456789A",
    "document": {
      "id": "doc_550e8400-e29b-41d4-a716-446655440000",
      "uuid": "12345678-1234-1234-1234-123456789012",
      "type": "INVOICE",
      "issueDate": "2024-03-15T10:30:00Z",
      "amount": 1160.00,
      "currency": "MXN",
      "emitter": {
        "rfc": "XYZ020202XYZ",
        "name": "Proveedor XYZ S.A. de C.V."
      },
      "receiver": {
        "rfc": "ABC010101ABC",
        "name": "Empresa ABC S.A. de C.V."
      },
      "availableFormats": ["XML", "PDF"]
    }
  }
}

Webhook endpoint implementation

const express = require('express');
const crypto = require('crypto');
const app = express();

// Middleware para capturar el body raw (necesario para verificar firma)
app.use('/webhooks/taxo', express.raw({ type: 'application/json' }));

app.post('/webhooks/taxo', (req, res) => {
  const signature = req.headers['x-taxo-signature'];
  const timestamp = req.headers['x-taxo-timestamp'];
  const payload = req.body;
  
  // Verificar que el webhook no sea muy antiguo (5 minutos)
  const webhookTimestamp = parseInt(timestamp);
  const currentTime = Math.floor(Date.now() / 1000);
  if (currentTime - webhookTimestamp > 300) {
    return res.status(400).json({ error: 'Webhook too old' });
  }
  
  // Verificar firma HMAC (si tienes secreto configurado)
  const webhookSecret = process.env.TAXO_WEBHOOK_SECRET;
  if (webhookSecret && signature) {
    const expectedSignature = crypto
      .createHmac('sha256', webhookSecret)
      .update(timestamp + '.' + payload)
      .digest('hex');
    
    if (signature !== `sha256=${expectedSignature}`) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
  }
  
  // Parsear el payload
  const event = JSON.parse(payload.toString());
  
  // Procesar evento
  try {
    handleWebhookEvent(event);
    
    // Responder con 200 para confirmar recepción
    res.status(200).json({ received: true });
    
  } catch (error) {
    console.error('Error procesando webhook:', error);
    res.status(500).json({ error: 'Processing failed' });
  }
});

function handleWebhookEvent(event) {
  console.log(`Event received: ${event.event.type}`);
  
  switch (event.event.type) {
    case 'extraction.completed':
      handleExtractionCompleted(event.data);
      break;
      
    case 'extraction.failed':
      handleExtractionFailed(event.data);
      break;
      
    case 'document.ready':
      handleDocumentReady(event.data);
      break;
      
    default:
      console.log(`Unhandled event type: ${event.event.type}`);
  }
}

function handleExtractionCompleted(data) {
  console.log(`✅ Extraction ${data.extractionId} completed:`);
  console.log(`   - ${data.summary.successfulDownloads} documents downloaded`);
  console.log(`   - ${data.summary.failedDownloads} failures`);
  
  // Here you can:
  // - Update status in your database
  // - Send email notification
  // - Start automatic document download
  // - Process documents with your business logic
}

function handleExtractionFailed(data) {
  console.error(`❌ Extraction ${data.extractionId} failed:`);
  console.error(`   Error: ${data.error.message}`);
  
  // Here you can:
  // - Mark extraction as failed in your DB
  // - Send alert to support team
  // - Attempt reprocessing if error is recoverable
}

function handleDocumentReady(data) {
  console.log(`📄 Document ready: ${data.document.uuid}`);
  
  // Process individual document
  // - Download automatically
  // - Extract specific data
  // - Notify downstream systems
}

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

from fastapi import FastAPI, Request, HTTPException, Header
import hmac
import hashlib
import json
import time
from typing import Optional

app = FastAPI()

WEBHOOK_SECRET = os.environ.get('TAXO_WEBHOOK_SECRET')

@app.post("/webhooks/taxo")
async def webhook_handler(
    request: Request,
    x_taxo_signature: Optional[str] = Header(None),
    x_taxo_timestamp: Optional[str] = Header(None)
):
    # Obtener body raw
    body = await request.body()
    
    # Verificar timestamp (no más de 5 minutos de antigüedad)
    if x_taxo_timestamp:
        webhook_timestamp = int(x_taxo_timestamp)
        current_time = int(time.time())
        if current_time - webhook_timestamp > 300:
            raise HTTPException(status_code=400, detail="Webhook too old")
    
    # Verificar firma HMAC
    if WEBHOOK_SECRET and x_taxo_signature:
        expected_signature = hmac.new(
            WEBHOOK_SECRET.encode(),
            f"{x_taxo_timestamp}.{body.decode()}".encode(),
            hashlib.sha256
        ).hexdigest()
        
        if x_taxo_signature != f"sha256={expected_signature}":
            raise HTTPException(status_code=401, detail="Invalid signature")
    
    # Parsear evento
    try:
        event = json.loads(body.decode())
    except json.JSONDecodeError:
        raise HTTPException(status_code=400, detail="Invalid JSON")
    
    # Procesar evento
    try:
        await handle_webhook_event(event)
        return {"received": True}
    except Exception as e:
        print(f"Error procesando webhook: {e}")
        raise HTTPException(status_code=500, detail="Processing failed")

async def handle_webhook_event(event: dict):
    event_type = event["event"]["type"]
    data = event["data"]
    
    print(f"Evento recibido: {event_type}")
    
    if event_type == "extraction.completed":
        await handle_extraction_completed(data)
    elif event_type == "extraction.failed":
        await handle_extraction_failed(data)
    elif event_type == "document.ready":
        await handle_document_ready(data)
    else:
        print(f"Tipo de evento no manejado: {event_type}")

async def handle_extraction_completed(data: dict):
    extraction_id = data["extractionId"]
    summary = data["summary"]
    
    print(f"✅ Extracción {extraction_id} completada:")
    print(f"   - {summary['successfulDownloads']} documentos descargados")
    print(f"   - {summary['failedDownloads']} fallos")
    
    # Implementar lógica de negocio aquí
    # - Actualizar base de datos
    # - Enviar notificaciones
    # - Iniciar procesamientos adicionales

async def handle_extraction_failed(data: dict):
    extraction_id = data["extractionId"]
    error = data["error"]
    
    print(f"❌ Extracción {extraction_id} falló:")
    print(f"   Error: {error['message']}")
    
    # Implementar manejo de errores
    # - Logging detallado
    # - Alertas al equipo
    # - Lógica de retry si aplica

async def handle_document_ready(data: dict):
    document = data["document"]
    print(f"📄 Documento listo: {document['uuid']}")
    
    # Procesar documento individual
    # - Descarga automática
    # - Extracción de datos
    # - Integración con otros sistemas

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

@RestController
@RequestMapping("/webhooks")
public class TaxoWebhookController {
    
    @Value("${taxo.webhook.secret:}")
    private String webhookSecret;
    
    @PostMapping(value = "/taxo", consumes = "application/json")
    public ResponseEntity<?> handleWebhook(
            @RequestBody String payload,
            @RequestHeader(value = "X-Taxo-Signature", required = false) String signature,
            @RequestHeader(value = "X-Taxo-Timestamp", required = false) String timestamp) {
        
        try {
            // Verificar timestamp
            if (timestamp != null) {
                long webhookTimestamp = Long.parseLong(timestamp);
                long currentTime = System.currentTimeMillis() / 1000;
                if (currentTime - webhookTimestamp > 300) {
                    return ResponseEntity.badRequest().body("Webhook too old");
                }
            }
            
            // Verificar firma HMAC
            if (!webhookSecret.isEmpty() && signature != null) {
                String expectedSignature = calculateHmacSha256(timestamp + "." + payload, webhookSecret);
                if (!signature.equals("sha256=" + expectedSignature)) {
                    return ResponseEntity.status(401).body("Invalid signature");
                }
            }
            
            // Parsear evento
            ObjectMapper mapper = new ObjectMapper();
            JsonNode event = mapper.readTree(payload);
            
            // Procesar evento
            handleWebhookEvent(event);
            
            return ResponseEntity.ok(Map.of("received", true));
            
        } catch (Exception e) {
            logger.error("Error procesando webhook", e);
            return ResponseEntity.status(500).body("Processing failed");
        }
    }
    
    private void handleWebhookEvent(JsonNode event) {
        String eventType = event.get("event").get("type").asText();
        JsonNode data = event.get("data");
        
        logger.info("Evento recibido: {}", eventType);
        
        switch (eventType) {
            case "extraction.completed":
                handleExtractionCompleted(data);
                break;
            case "extraction.failed":
                handleExtractionFailed(data);
                break;
            case "document.ready":
                handleDocumentReady(data);
                break;
            default:
                logger.warn("Tipo de evento no manejado: {}", eventType);
        }
    }
    
    private void handleExtractionCompleted(JsonNode data) {
        String extractionId = data.get("extractionId").asText();
        JsonNode summary = data.get("summary");
        
        logger.info("✅ Extracción {} completada:", extractionId);
        logger.info("   - {} documentos descargados", 
                   summary.get("successfulDownloads").asInt());
        logger.info("   - {} fallos", summary.get("failedDownloads").asInt());
        
        // Implementar lógica de negocio
    }
    
    private void handleExtractionFailed(JsonNode data) {
        String extractionId = data.get("extractionId").asText();
        String errorMessage = data.get("error").get("message").asText();
        
        logger.error("❌ Extracción {} falló: {}", extractionId, errorMessage);
        
        // Implementar manejo de errores
    }
    
    private void handleDocumentReady(JsonNode data) {
        String documentUuid = data.get("document").get("uuid").asText();
        logger.info("📄 Documento listo: {}", documentUuid);
        
        // Procesar documento individual
    }
    
    private String calculateHmacSha256(String data, String secret) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
            mac.init(secretKeySpec);
            byte[] hash = mac.doFinal(data.getBytes());
            return bytesToHex(hash);
        } catch (Exception e) {
            throw new RuntimeException("Error calculating HMAC", e);
        }
    }
    
    private String bytesToHex(byte[] bytes) {
        StringBuilder result = new StringBuilder();
        for (byte b : bytes) {
            result.append(String.format("%02x", b));
        }
        return result.toString();
    }
}

Signature verification

Webhooks include an HMAC-SHA256 signature to verify their authenticity:

Get data

timestamp: Header X-Taxo-Timestamp
signature: Header X-Taxo-Signature
payload: Body raw del webhook

Build string to sign

Concatenate: timestamp + "." + payload

Calculate HMAC

Use your webhook secret to calculate HMAC-SHA256 of the previous string

Compare signatures

The received signature should equal sha256={your_calculated_hmac}

Best practices

Idempotencia

Los webhooks pueden enviarse múltiples veces. Usa el campo event.timestamp como clave de idempotencia para evitar procesamiento duplicado.

const processedEvents = new Set();

function handleWebhookEvent(event) {
  const eventKey = `${event.event.type}_${event.event.timestamp}`;
  
  if (processedEvents.has(eventKey)) {
    console.log('Evento ya procesado, ignorando');
    return;
  }
  
  // Procesar evento...
  processedEvents.add(eventKey);
}

Timeouts y reintentos

Configura timeouts apropiados en tu endpoint:

Timeout de respuesta: 10 segundos máximo
Procesamiento asíncrono: Para tareas largas, responde 200 inmediatamente y procesa en background
Reintentos automáticos: Taxo reintentará hasta 5 veces con backoff exponencial

Logging y monitoreo

Implementa logging detallado para debugging:

function handleWebhookEvent(event) {
  const correlationId = crypto.randomUUID();
  
  console.log(`[${correlationId}] Webhook recibido:`, {
    type: event.event.type,
    timestamp: event.event.timestamp,
    extractionId: event.data.extractionId
  });
  
  try {
    // Procesar evento...
    console.log(`[${correlationId}] Evento procesado exitosamente`);
  } catch (error) {
    console.error(`[${correlationId}] Error procesando webhook:`, error);
    throw error;
  }
}

Seguridad

HTTPS obligatorio: Los webhooks solo se envían a URLs HTTPS
Verificar firma: Siempre valida la firma HMAC en producción
Validar timestamp: Rechaza webhooks muy antiguos (más de 5 minutos)
Rate limiting: Implementa protección contra ataques de denegación de servicio

Testing and debugging

Test webhooks locally

To test webhooks in local development, use tools like ngrok:

# Install ngrok
npm install -g ngrok

# Expose local port
ngrok http 3000

# Use the public URL in webhook configuration
# Ejemplo: https://abc123.ngrok.io/webhooks/taxo

Test webhook

You can test your endpoint with this example payload:

curl -X POST "https://tu-dominio.com/webhooks/taxo" \
  -H "Content-Type: application/json" \
  -H "X-Taxo-Signature: sha256=test" \
  -H "X-Taxo-Timestamp: $(date +%s)" \
  -d '{
    "event": {
      "type": "extraction.completed",
      "timestamp": "2025-01-04T13:15:42.123Z",
      "version": "1.0"
    },
    "data": {
      "extractionId": "TEST123456789",
      "status": "COMPLETED",
      "summary": {
        "totalDocuments": 100,
        "successfulDownloads": 98,
        "failedDownloads": 2
      }
    }
  }'

Troubleshooting

Webhook no se recibe

Verifica que la URL esté configurada correctamente
Asegúrate de que tu endpoint responda con status 2xx
Revisa que no haya firewalls bloqueando las IPs de Taxo
Confirma que el certificado SSL sea válido

Error de firma inválida

Verifica que el secreto webhook esté configurado correctamente
Asegúrate de usar el body raw (no parseado) para calcular la firma
Confirma que estás concatenando timestamp + ”.” + payload
Verifica que el algoritmo sea HMAC-SHA256

Webhooks duplicados

Implementa idempotencia usando el timestamp del evento
Almacena IDs de eventos procesados en cache/base de datos
Responde siempre con 200 even si el evento ya fue procesado

Getting Started

SAT API Reference

Document Types

Use Cases

Webhooks

What are webhooks?

Real-time

Efficiency

Reliability

Security

Webhook configuration

Event types

extraction.completed

extraction.failed

document.ready

Webhook endpoint implementation

Signature verification

Best practices

Testing and debugging

Test webhooks locally

Test webhook

Troubleshooting

​What are webhooks?

Real-time

Efficiency

Reliability

Security

​Webhook configuration

​Event types

​extraction.completed

​extraction.failed

​document.ready

​Webhook endpoint implementation

​Signature verification

​Best practices

​Testing and debugging

​Test webhooks locally

​Test webhook

​Troubleshooting

What are webhooks?

Webhook configuration

Event types

extraction.completed

extraction.failed

document.ready

Webhook endpoint implementation

Signature verification

Best practices

Testing and debugging

Test webhooks locally

Test webhook

Troubleshooting