--- updatedAt: 2026-04-21T17:01:30.000Z agentTools: projectIndex: https://developers.burodeingresos.com/llms.txt --- # Create Webhook Registers a new webhook URL to receive notifications for verification events. Users can optionally specify which events to subscribe to using the 'events' array. Supports `verification.completed` (when verification finishes) and `verification.historical` (when historical employment data becomes available) events. If events are not specified, the webhook subscribes to all available events by default. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Buró de Ingresos API", "version": "v1.2.24", "description": "Verify income and employment data with just a CURP. Made with ❤️ in Mexico 🇲🇽" }, "servers": [ { "url": "https://api.burodeingresos.com", "description": "Production server" } ], "tags": [ { "name": "Webhooks", "description": "Endpoints for managing webhook notifications for verification events." } ], "paths": { "/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Create Webhook", "description": "Registers a new webhook URL to receive notifications for verification events. Users can optionally specify which events to subscribe to using the 'events' array. Supports `verification.completed` (when verification finishes) and `verification.historical` (when historical employment data becomes available) events. If events are not specified, the webhook subscribes to all available events by default.", "operationId": "createWebhook", "x-readme": { "slug": "create-webhook" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" }, "examples": { "example_no_auth": { "summary": "Webhook without authentication", "value": { "description": "Simple webhook for development/testing", "endpoint_url": "https://yourapi.com/webhook/simple" } }, "example_jwt": { "summary": "Webhook with JWT authentication", "value": { "description": "Production webhook using JWT", "endpoint_url": "https://yourapi.com/webhook/jwt", "authentication": { "type": "jwt", "secret": "supersecretkey123", "expiration_seconds": 3600 } } }, "example_custom_headers": { "summary": "Webhook with custom headers", "value": { "description": "Webhook using custom headers", "endpoint_url": "https://yourapi.com/webhook/headers", "authentication": { "type": "custom_headers", "headers": { "X-Api-Key": "apikey123", "X-Client-Id": "client456" } } } }, "example_token_endpoint": { "summary": "Webhook fetching token from endpoint", "value": { "description": "Webhook with token endpoint authentication", "endpoint_url": "https://yourapi.com/webhook/token", "authentication": { "type": "token_endpoint", "url": "https://authserver.com/get-token", "method": "POST", "request_headers": { "Content-Type": "application/json" }, "request_body": { "client_id": "abc123", "client_secret": "secret456" }, "response_key": "access_token" } } }, "example_with_specific_events": { "summary": "Subscribe to completion events only", "value": { "description": "Webhook subscribed to completion events only", "endpoint_url": "https://yourapi.com/webhook/completed", "events": [ "verification.completed" ] } }, "example_historical_only": { "summary": "Subscribe to historical events only", "value": { "description": "Webhook subscribed to historical events only", "endpoint_url": "https://yourapi.com/webhook/historical", "events": [ "verification.historical" ] } } } } } }, "responses": { "201": { "description": "Webhook created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "examples": { "created_no_auth": { "summary": "Simple webhook created without authentication", "value": { "id": "9e274c08-6ba4-4f73-b107-690c665359af", "company_id": "570cc1f0-8813-4138-8cd5-ad166a5d4a48", "description": "Simple webhook for development/testing", "endpoint_url": "https://yourapi.com/webhook/simple", "secret_key": "UCi8NBZV6prNoqcXywHLDAD23tWjONhwlZ4NDd-Y7u", "is_active": true, "events": [ "verification.completed", "verification.historical" ], "created_at": "2025-09-15T22:57:54.291054Z", "updated_at": "2025-09-15T22:57:54.291054Z" } }, "created_jwt": { "summary": "JWT webhook created", "value": { "id": "9e274c08-6ba4-4f73-b107-690c665359af", "company_id": "570cc1f0-8813-4138-8cd5-ad166a5d4a48", "description": "Production webhook using JWT", "endpoint_url": "https://yourapi.com/webhook/jwt", "secret_key": "UCi8NBZV6prNoqcXywHLDAD23tWjONhwlZ4NDd-Y7u", "is_active": true, "events": [ "verification.completed", "verification.historical" ], "created_at": "2025-09-15T22:57:54.291054Z", "updated_at": "2025-09-15T22:57:54.291054Z", "authentication": { "type": "jwt", "secret": "supersecretkey123", "expiration_seconds": 3600 } } }, "created_custom_headers": { "summary": "Custom headers webhook created", "value": { "id": "9e274c08-6ba4-4f73-b107-690c665359af", "company_id": "570cc1f0-8813-4138-8cd5-ad166a5d4a48", "description": "Webhook using custom headers", "endpoint_url": "https://yourapi.com/webhook/headers", "secret_key": "UCi8NBZV6prNoqcXywHLDAD23tWjONhwlZ4NDd-Y7u", "is_active": true, "events": [ "verification.completed", "verification.historical" ], "created_at": "2025-09-15T22:57:54.291054Z", "updated_at": "2025-09-15T22:57:54.291054Z", "authentication": { "type": "custom_headers", "headers": { "X-Api-Key": "apikey123", "X-Client-Id": "client456" } } } }, "created_token_endpoint": { "summary": "Token endpoint webhook created", "value": { "id": "9e274c08-6ba4-4f73-b107-690c665359af", "company_id": "570cc1f0-8813-4138-8cd5-ad166a5d4a48", "description": "Webhook with token endpoint authentication", "endpoint_url": "https://yourapi.com/webhook/token", "secret_key": "UCi8NBZV6prNoqcXywHLDAD23tWjONhwlZ4NDd-Y7u", "is_active": true, "events": [ "verification.completed", "verification.historical" ], "created_at": "2025-09-15T22:57:54.291054Z", "updated_at": "2025-09-15T22:57:54.291054Z", "authentication": { "type": "token_endpoint", "url": "https://authserver.com/get-token", "method": "POST", "request_headers": { "Content-Type": "application/json" }, "request_body": { "client_id": "abc123", "client_secret": "secret456" }, "response_key": "access_token" } } } } } } }, "400": { "description": "Bad Request - Invalid events array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "empty_events": { "summary": "Empty events array", "value": { "error": { "code": "INVALID_EVENTS", "message": "Events array must contain at least one valid event type", "details": "Allowed events: verification.completed, verification.historical" } } }, "invalid_event_type": { "summary": "Invalid event type", "value": { "error": { "code": "INVALID_EVENT_TYPE", "message": "One or more invalid event types provided", "details": "Invalid events: [verification.test]. Allowed events: verification.completed, verification.historical" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unauthorized": { "summary": "Invalid API key", "value": { "error": "Unauthorized", "message": "Invalid X-API-Key" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "WebhookCreate": { "type": "object", "required": [ "endpoint_url" ], "properties": { "description": { "type": "string", "description": "Description of the webhook.", "example": "Production verification notifications" }, "endpoint_url": { "type": "string", "format": "uri", "description": "The URL to send the webhook notifications to.", "example": "https://yourapi.com/webhook/handler" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "verification.completed", "verification.historical" ] }, "minItems": 1, "uniqueItems": true, "default": [ "verification.completed", "verification.historical" ], "description": "Array of event types to subscribe to. If not provided, defaults to all available events.", "example": [ "verification.completed", "verification.historical" ] }, "authentication": { "type": "object", "description": "Authentication configuration for the webhook.", "oneOf": [ { "type": "object", "required": [ "type", "secret", "expiration_seconds" ], "properties": { "type": { "type": "string", "enum": [ "jwt" ] }, "secret": { "type": "string", "description": "Secret used to generate the JWT." }, "expiration_seconds": { "type": "integer", "description": "Expiration time of the JWT in seconds." } } }, { "type": "object", "required": [ "type", "headers" ], "properties": { "type": { "type": "string", "enum": [ "custom_headers" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom headers to include in the webhook request." } } }, { "type": "object", "required": [ "type", "url", "method", "response_key" ], "properties": { "type": { "type": "string", "enum": [ "token_endpoint" ] }, "url": { "type": "string", "format": "uri", "description": "URL to fetch the token from." }, "method": { "type": "string", "enum": [ "GET", "POST" ], "default": "POST" }, "request_headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Headers to send with the token request." }, "request_body": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Body to send with the token request." }, "response_key": { "type": "string", "description": "Key to extract the token from the response." } } } ] } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the webhook." }, "company_id": { "type": "string", "format": "uuid", "description": "Company identifier owning the webhook." }, "description": { "type": "string", "description": "Description of the webhook." }, "endpoint_url": { "type": "string", "format": "uri", "description": "URL to send the webhook notifications to." }, "secret_key": { "type": "string", "description": "A secret key used to verify the signature in the X-Signature header of the webhook, ensuring that the webhook request originates from the Income Bureau." }, "is_active": { "type": "boolean", "description": "Whether the webhook is active." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "verification.completed", "verification.historical" ] }, "description": "Array of event types this webhook is subscribed to.", "example": [ "verification.completed", "verification.historical" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the webhook was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the webhook was last updated." }, "authentication": { "type": "object", "description": "Authentication configuration for the webhook.", "oneOf": [ { "type": "object", "required": [ "type", "secret", "expiration_seconds" ], "properties": { "type": { "type": "string", "enum": [ "jwt" ] }, "secret": { "type": "string" }, "expiration_seconds": { "type": "integer" } } }, { "type": "object", "required": [ "type", "headers" ], "properties": { "type": { "type": "string", "enum": [ "custom_headers" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } } }, { "type": "object", "required": [ "type", "url", "method", "response_key" ], "properties": { "type": { "type": "string", "enum": [ "token_endpoint" ] }, "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "enum": [ "GET", "POST" ], "default": "POST" }, "request_headers": { "type": "object", "additionalProperties": { "type": "string" } }, "request_body": { "type": "object", "additionalProperties": { "type": "string" } }, "response_key": { "type": "string" } } } ] } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } } }, "ErrorDetail": { "type": "object", "properties": { "code": { "type": "string", "description": "A machine-readable error code." }, "message": { "type": "string", "description": "A human-readable message providing a summary of the error." }, "details": { "type": "string", "description": "Additional details about the error, which can help in debugging." } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API Key for authenticating requests." } } } } ```