Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/NemonInvocash/verifactu-php/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks allow your application to receive automatic HTTP POST notifications from VeriFactuAPI whenever an invoice record changes state — for example when it is accepted or rejected by AEAT. Instead of polling the API for updates, you register a publicly accessible endpoint on your server and VeriFactuAPI calls it with the relevant event data.

​
Create a Webhook

Call createWebhook() with the URL of your receiving endpoint. The method registers the webhook with VeriFactuAPI and returns the integer ID assigned to it: 
$webhookId = $client->createWebhook('https://yourapp.com/webhook/{id}');
echo "Webhook created with ID: $webhookId";
The URL may include the {id} placeholder, which VeriFactuAPI replaces with the relevant record ID when it dispatches the notification. This makes it easy to route incoming events to the correct handler on your server.
Internally, createWebhook() POSTs to /api/webhook with http_method set to POST. The returned integer ID is what you pass to emisores and invoice records to wire up notifications.

​
List Registered Webhooks

Use listarWebhooks() to retrieve webhooks previously registered under your account. Call it with no arguments to get all webhooks, or pass an integer ID to fetch a specific one: 
// Retrieve all registered webhooks
$webhooks = $client->listarWebhooks();

// Retrieve a specific webhook by its ID
$webhook = $client->listarWebhooks(5);
Call listarWebhooks() before creating a new webhook to check whether an endpoint is already registered. This helps avoid creating duplicate webhook entries for the same URL.

​
Associate a Webhook with an Emisor

To route VeriFactuAPI notifications for a specific emisor to your endpoint, pass the webhookID when creating the emisor. This sets the default_webhook_id field on the emisor record: 
$emisor = $client->nuevoEmisor([
    'nif'        => 'A39200019',
    'nombre'     => 'Mi Empresa S.L.',
    'enviarAeat' => true,
    'webhookID'  => $webhookId,
]);

$client->altaEmisor($emisor);

​
Webhook Inheritance on Invoice Records

When you create a RegistroAlta without explicitly specifying a $webhookID, verifactuPHP automatically inherits the webhook ID from the associated emisor: 
$desglose = $client->nuevoDesglose([
    'impuesto'                      => '01',
    'claveRegimen'                  => 1,
    'tipoImpositivo'                => 21,
    'baseImponibleOImporteNoSujeto' => 100,
    'cuotaRepercutida'              => 21,
]);

// No webhookID passed — falls back to $emisor->getWebhookID()
$registroAlta = $client->nuevoRegistroAlta(
    ['emisor' => $emisor, 'desglose' => $desglose],
    [
        'numSerieFactura'        => 'AX/202412-118',
        'fechaExpedicionFactura' => '2024-12-16',
        'tipoFactura'            => 'F1',
        'cuotaTotal'             => 21.0,
        'importeTotal'           => 121.0,
    ]
);
To override the emisor’s default webhook for a specific record, pass the desired ID as the third argument to nuevoRegistroAlta(): 
$registroAlta = $client->nuevoRegistroAlta(
    ['emisor' => $emisor, 'desglose' => $desglose],
    ['numSerieFactura' => 'AX/202412-118', /* ... */],
    $webhookId  // explicit override
);

Build docs developers (and LLMs) love

Get started for freeTalk to us