# Crear un webhook

`POST https://api.fiscalisto.com/v1/webhook_endpoints`

La respuesta trae el secreto de firma (secret) una sola vez.

## Parámetros

| Nombre | Dónde | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `Idempotency-Key` | encabezado |  | Opcional (los SDK la mandan solos). Si la respuesta se pierde, repita la solicitud con el mismo valor durante 24 horas: contesta lo mismo, con idempotent-replayed: true, y no lo hace dos veces (ni crea, ni manda correos, ni cobra). |

## Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `url` | string | sí | Dirección https de su servidor que recibe los avisos. (hasta 2048 caracteres) |
| `events` | arreglo de string o null |  | Eventos que quiere recibir, o ["*"] para todos (por omisión). La lista con cuándo llega cada uno: [Tipos de evento](https://fiscalisto.com/docs/api/webhooks#tipos-de-evento). |
| `description` | string o null |  | Para qué es, para usted (no se manda en los eventos). |
| `api_version` | string o null |  | La versión de la API en que llegan sus eventos (por ejemplo 2026-10-24); null o sin mandar: la de la cuenta. Así actualiza un endpoint a la vez. |

Ejemplo:

```json
{
  "url": "https://mi-plataforma.mx/webhooks/fiscalisto",
  "events": [
    "invoice.stamped",
    "invoice.failed",
    "invoice.canceled"
  ]
}
```

## Con el SDK de TypeScript

```ts
import { Fiscalisto } from "fiscalisto";

// La llave viene de FISCALISTO_API_KEY.
const fiscalisto = new Fiscalisto();

const webhookEndpoint = await fiscalisto.webhookEndpoints.create({
  url: "https://mi-plataforma.mx/webhooks/fiscalisto",
  events: [
    "invoice.stamped",
    "invoice.failed",
    "invoice.canceled",
  ],
}, { idempotencyKey: "pedido-A-1042" });
```

## Con el SDK de Python

```python
from fiscalisto import Fiscalisto

# La llave viene de FISCALISTO_API_KEY.
fiscalisto = Fiscalisto()

webhook_endpoint = fiscalisto.webhook_endpoints.create({
    "url": "https://mi-plataforma.mx/webhooks/fiscalisto",
    "events": [
        "invoice.stamped",
        "invoice.failed",
        "invoice.canceled",
    ],
}, idempotency_key="pedido-A-1042")
```

## Con el SDK de PHP

```php
<?php

use Fiscalisto\Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
$fiscalisto = new Fiscalisto();

$webhookEndpoint = $fiscalisto->webhookEndpoints->create([
    'url' => 'https://mi-plataforma.mx/webhooks/fiscalisto',
    'events' => [
        'invoice.stamped',
        'invoice.failed',
        'invoice.canceled',
    ],
], ['idempotency_key' => 'pedido-A-1042']);
```

## Con el SDK de .NET

```csharp
using Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var webhookEndpoint = await fiscalisto.WebhookEndpoints.CreateAsync(new CreateWebhookEndpointParams
{
    Url = "https://mi-plataforma.mx/webhooks/fiscalisto",
    Events = new()
    {
        "invoice.stamped",
        "invoice.failed",
        "invoice.canceled",
    },
}, new RequestOptions { IdempotencyKey = "pedido-A-1042" });
```

## Con el SDK de Go

```go
package main

import (
	"context"
	"fmt"
	"log"

	fiscalisto "fiscalisto.com/go"
)

func main() {
	// La llave viene de FISCALISTO_API_KEY.
	client, err := fiscalisto.NewClient("")
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	webhookEndpoint, err := client.WebhookEndpoints.Create(ctx, &fiscalisto.CreateWebhookEndpointParams{
		URL: "https://mi-plataforma.mx/webhooks/fiscalisto",
		Events: []string{
			"invoice.stamped",
			"invoice.failed",
			"invoice.canceled",
		},
	}, fiscalisto.WithIdempotencyKey("pedido-A-1042"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(webhookEndpoint.ID)
}
```

## Con el SDK de Java

```java
import com.fiscalisto.FiscalistoClient;
import com.fiscalisto.RequestOptions;
import com.fiscalisto.model.CreateWebhookEndpointParams;
import java.util.List;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var webhookEndpoint = fiscalisto.webhookEndpoints().create(new CreateWebhookEndpointParams()
        .setUrl("https://mi-plataforma.mx/webhooks/fiscalisto")
        .setEvents(List.of(
                "invoice.stamped",
                "invoice.failed",
                "invoice.canceled"
        )), RequestOptions.idempotencyKey("pedido-A-1042"));
System.out.println(webhookEndpoint.getId());
```

## Respuesta 201

Correcto.

Un objeto `WebhookEndpoint`:

| Campo | Tipo | Siempre viene | Descripción |
| --- | --- | --- | --- |
| `id` | string | sí | Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). |
| `livemode` | boolean | sí | true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. |
| `object` | `"webhook_endpoint"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `sandbox` | string o null | sí | El entorno de prueba (sbx_…) al que pertenece, o null si es de la cuenta. Vea /v1/sandboxes. |
| `url` | string | sí | Dirección https de su servidor que recibe los avisos. |
| `description` | string o null | sí | Para qué es, para usted. |
| `events` | arreglo de string | sí | Eventos que quiere recibir, o ["*"] para todos (por omisión). La lista con cuándo llega cada uno: [Tipos de evento](https://fiscalisto.com/docs/api/webhooks#tipos-de-evento). |
| `status` | `enabled`, `failing`, `disabled` | sí | enabled: entregando. failing: sus entregas fallan (se apaga tras 5 días así). disabled: apagado. |
| `disabled_reason` | string o null |  | Por qué se apagó (sus entregas fallaron 5 días seguidos, o usted lo apagó). |
| `failing_since` | string (date-time) o null |  | Desde cuándo fallan las entregas, o null. |
| `previous_secret_expires_at` | string (date-time) o null | sí | Hasta cuándo el secreto anterior también firma (después de cambiarlo), o null. |
| `api_version` | string o null | sí | La versión de la API de sus eventos; null: la de la cuenta. |
| `created_at` | string (date-time) o null | sí | Cuándo se creó, ISO 8601 con la hora de la Ciudad de México (-06:00). |
| `secret` | string |  | Secreto de firma (whsec_…). Solo viene al crearlo o al cambiarlo: guárdelo para verificar las firmas. |

```json
{
  "id": "whe_0q1Vmmw52sbDpmtsKD1E",
  "object": "webhook_endpoint",
  "livemode": false,
  "sandbox": null,
  "url": "https://mi-plataforma.mx/webhooks/fiscalisto",
  "description": null,
  "events": [
    "invoice.stamped"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "failing_since": null,
  "previous_secret_expires_at": null,
  "api_version": null,
  "created_at": "2026-10-24T10:15:42-06:00",
  "secret": "whsec_MfKQ9r7Cq1ZzR0nN3xY2bW8eT5uV6sA4"
}
```

## Errores

Puede responder 400, 401, 403, 404, 429, 500 con el cuerpo de error de siempre; cada código está en https://fiscalisto.com/docs/api/errores.md.