Webhooks

📘

Information

We strongly recommend enabling webhook notifications. Buró de Ingresos' verification processes vary by data source and can take anywhere from 10 seconds to 8 minutes depending on your configuration.

When properly implemented, webhooks allow you to automatically trigger backend processes that rely on employment and income verification data.

Below, we provide use cases and examples to help you integrate webhook notifications successfully.

Introduction

Webhooks allow Buró de Ingresos to communicate with your application in real-time. All you need to do is provide us with a URL to which we can send notifications (HTTP POST requests) to keep you updated on the status of your verification requests. The details of each event are sent in the request body in JSON format, allowing you to automatically trigger processes in your backend.

Let's jump right into creating your first webhook!

Create Your First Webhook

To register a webhook in the Buró de Ingresos Console, follow these steps:

1. Log in to your Console account
2. Go to the </> Developers section on the left side of your Console menu
3. Open the Webhooks tab
4. Click on the Create Webhook button
5. Choose a name for your webhook and register its URL (you can use a tool like webhook.site to perform quick tests)
6. Choose the webhook events you want to listen to
7. Click on Create webhook
8. Test your webhook by making verification requests through our API and validate that events are received at your registered URL

Note: You can see webhook events in the Console too. Just click on your webhook and the event logs will appear.

Data Schema of Webhook Events

We use a standardized data schema for webhook events:

{
  "event": "string",
  "verification_id": "string",
  "identifier": "string", 
  "status": "string",
  "data_available": "boolean",
  "entities": ["array"],
  "last_updated_at": "string",
  "timestamp": "string"
}

Webhook Notification Example

Let's say you integrated webhook notifications and one of your CURP verifications completed successfully with employment and invoice data. Here is an example of the request body your API could receive:

{
  "event": "verification.completed",
  "verification_id": "bd830637-ea6e-4888-80ab-a09f01fc9209",
  "identifier": "OICE940722HGFRST08",
  "status": "success",
  "data_available": true,
  "entities": ["profile", "summary", "employment_history", "invoices"],
  "last_updated_at": "2025-04-29T10:37:25Z",
  "timestamp": "2025-04-29T10:37:25Z"
}

Webhook Events Catalog

The unified API triggers webhook events during the verification process:

Understanding Verification Status

The verification process can result in different outcomes:

• success: Verification completed and data was found
• no_data: Verification completed but no data was found for the identifier
• error: Verification failed due to system errors or data source unavailability

Retries

If we do not receive a 200 or 201 status code within 30 seconds after the first POST request to your webhook URL, we will make up to three additional attempts (stopping if we receive a 200 or 201), waiting approximately 30 seconds between each attempt.

Example Events

Successful Verification with Full Data

{
  "event": "verification.completed",
  "verification_id": "bd830637-ea6e-4888-80ab-a09f01fc9209",
  "identifier": "OICE940722HGFRST08",
  "status": "success",
  "data_available": true,
  "entities": ["profile", "summary", "employment_history", "invoices"],
  "last_updated_at": "2025-04-29T10:37:25Z",
  "timestamp": "2025-04-29T10:37:25Z"
}

Successful Verification with Partial Data

{
  "event": "verification.completed",
  "verification_id": "bd830637-ea6e-4888-80ab-a09f01fc9217",
  "identifier": "OICE940722HGFRST08",
  "status": "success",
  "data_available": true,
  "entities": ["profile", "summary", "employment_history"],
  "last_updated_at": "2025-04-29T10:38:25Z",
  "timestamp": "2025-04-29T10:38:25Z"
}

Verification with No Data Found

{
  "event": "verification.completed",
  "verification_id": "bd830637-ea6e-4888-80ab-a09f01fc9211",
  "identifier": "OICE940722HGFRST08",
  "status": "no_data",
  "data_available": false,
  "entities": [],
  "last_updated_at": "2025-04-29T10:32:15Z",
  "timestamp": "2025-04-29T10:32:15Z"
}

Verification Error

{
  "event": "verification.completed",
  "verification_id": "bd830637-ea6e-4888-80ab-a09f01fc9212",
  "identifier": "OICE940722HGFRST08",
  "status": "error",
  "data_available": false,
  "entities": [],
  "last_updated_at": "2025-04-29T10:33:15Z",
  "timestamp": "2025-04-29T10:33:15Z"
}

Available Entities

When a verification is successful, the entities array will contain one or more of the following:

• profile: Basic personal information (name, CURP, RFC, contact details, address)
• summary: Employment status and summarized income information
• employment_history: Detailed employment records from IMSS/ISSSTE
• invoices: Invoice and payment history from payroll and invoicing systems

IP Whitelisting

Consider implementing IP whitelisting for your webhook endpoints. Contact support for our current IP ranges.

Troubleshooting

Common Issues

1. Webhook not receiving events: Verify your endpoint URL is publicly accessible and returns 200/201
2. Timeout errors: Ensure your endpoint responds within 30 seconds
3. Missing data: Check the entities array to see what data is available
   

Migration from Legacy Webhooks

If you're migrating from the legacy user/account-based webhook system:

Key Changes

1. Event Structure: Events now center around verification_id instead of account_id
2. Identifier-Centric: Use CURP/RFC as the primary identifier
3. Simplified Events: Single verification.completed event instead of multiple login events
4. Entity-Based Data: The entities array tells you what data is available

Next Steps

1. Set up your webhook endpoint
2. Register it in the Console
3. Test with sample verification requests
4. Implement proper error handling and retry logic
5. Monitor webhook delivery through the Console dashboard

For additional support, contact our developer team or check the API documentation at