> For the complete documentation index, see [llms.txt](https://docs.zipnova.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zipnova.com/envios/recursos-api/cuentas-y-origenes/webhooks.md).

# Webhooks

Puedes crear webhooks ingresando a tu cuenta, o bien por hacerlo por API. Ante determinados eventos dispararemos estos webhooks para que puedas recibir en tu integración una notificación al instante.

{% hint style="info" %}
Cada evento disparado consiste de un **request POST** a la URL que determines, con algunos datos sobre el recurso relacionado.

Es importante que tu servidor **responda con un HTTP 200**, de lo contrario nuestro sistema reintentará el envío de la notificación una vez por hora durante 12 horas.
{% endhint %}

#### Topics

Actualmente, los tópicos a los que te puedes suscribir son:

* `status`: Se dispara cuando hay un cambio de estado en un envío 
* `shipment`: Se dispara cuando hay cualquier modificación en un envío 
* `account`: Se dispara cuando hay una modificación en los datos o preferencias de una cuenta 
* `account_balance`: Se dispara cuando hay un cambio en el saldo de la cuenta
* `stock`: Se dispara cuando hay un cambio en el stock de un SKU

#### Ejemplos del contenido de los Webhooks

{% code title="status" %}

```json
{
   "topic":"status",
   "timestamp":"2024-03-08T18:56:34+00:00",
   "data":{
      "account_id":11600,
      "shipment_id":3850099,
      "external_id":"test-1709820269",
      "status":"Pendiente de preparacion",
      "status_code":"documentation_ready",
      "direction":"forward"
   }
}
```

{% endcode %}

{% code title="shipment" overflow="wrap" %}

```json
{
   "topic":"shipment",
   "timestamp":"2024-03-08T18:56:34+00:00",
   "data":{
      "account_id":11600,
      "shipment_id":3850099,
      "external_id":"test-1709820269"
   }
}
```

{% endcode %}

## Listar webhooks

> Obtiene la lista de suscripciones a webhooks para una cuenta.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Shipping API V2","version":"2.0.0"},"tags":[{"name":"Webhooks","description":"Gestión de webhooks para notificaciones"}],"servers":[{"url":"https://api.zipnova.com.ar/v2","description":"v2 API - Argentina (AR)"},{"url":"https://api.zipnova.cl/v2","description":"v2 API - Chile (CL)"},{"url":"https://api.zipnova.com.mx/v2","description":"v2 API - México (MX)"}],"security":[{"basicAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","description":"Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña","scheme":"basic"},"bearerAuth":{"type":"http","description":"Token de autenticación Bearer OAuth para API V2","bearerFormat":"OAuth","scheme":"bearer"}},"schemas":{"WebhookResource":{"title":"Webhook","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"topic":{"type":"string","enum":["shipment","status","account","account_balance","stock"]},"url":{"type":"string","format":"url"}},"type":"object"}}},"paths":{"/accounts/{account_id}/webhooks":{"get":{"tags":["Webhooks"],"summary":"Listar webhooks","description":"Obtiene la lista de suscripciones a webhooks para una cuenta.","operationId":"67b70a7aa1a94f2d3a8e202060aa8aad","parameters":[{"name":"account_id","in":"path","description":"ID de la cuenta","required":true,"schema":{"type":"integer"}},{"name":"topic","in":"query","description":"Filtrar por tópico del webhook","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista paginada de webhooks","content":{"application/json":{"schema":{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookResource"}},"links":{"type":"object"},"meta":{"type":"object"}},"type":"object"}}}},"403":{"description":"Sin acceso a esta cuenta"},"404":{"description":"Cuenta no encontrada"}}}}}}
```

## Suscribir a webhook

> Suscribir a nuevo webhook para recibir notificaciones de eventos en una URL específica.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Shipping API V2","version":"2.0.0"},"tags":[{"name":"Webhooks","description":"Gestión de webhooks para notificaciones"}],"servers":[{"url":"https://api.zipnova.com.ar/v2","description":"v2 API - Argentina (AR)"},{"url":"https://api.zipnova.cl/v2","description":"v2 API - Chile (CL)"},{"url":"https://api.zipnova.com.mx/v2","description":"v2 API - México (MX)"}],"security":[{"basicAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","description":"Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña","scheme":"basic"},"bearerAuth":{"type":"http","description":"Token de autenticación Bearer OAuth para API V2","bearerFormat":"OAuth","scheme":"bearer"}},"schemas":{"WebhookResource":{"title":"Webhook","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"topic":{"type":"string","enum":["shipment","status","account","account_balance","stock"]},"url":{"type":"string","format":"url"}},"type":"object"}}},"paths":{"/accounts/{account_id}/webhooks":{"post":{"tags":["Webhooks"],"summary":"Suscribir a webhook","description":"Suscribir a nuevo webhook para recibir notificaciones de eventos en una URL específica.","operationId":"dfc7916bf0c7f0de519ad44103590fbc","parameters":[{"name":"account_id","in":"path","description":"ID de la cuenta","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["topic","url"],"properties":{"topic":{"description":"Tópico del evento a escuchar","type":"string","enum":["shipment","status","account","account_balance","stock"]},"url":{"description":"URL destino del webhook","type":"string","format":"url"}},"type":"object"}}}},"responses":{"201":{"description":"Webhook creado exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResource"}}}},"400":{"description":"Datos inválidos o webhook duplicado"},"403":{"description":"Sin acceso a esta cuenta"}}}}}}
```

## Actualizar suscripción a webhook

> Actualiza la URL de una suscripción a webhook existente.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Shipping API V2","version":"2.0.0"},"tags":[{"name":"Webhooks","description":"Gestión de webhooks para notificaciones"}],"servers":[{"url":"https://api.zipnova.com.ar/v2","description":"v2 API - Argentina (AR)"},{"url":"https://api.zipnova.cl/v2","description":"v2 API - Chile (CL)"},{"url":"https://api.zipnova.com.mx/v2","description":"v2 API - México (MX)"}],"security":[{"basicAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","description":"Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña","scheme":"basic"},"bearerAuth":{"type":"http","description":"Token de autenticación Bearer OAuth para API V2","bearerFormat":"OAuth","scheme":"bearer"}},"schemas":{"WebhookResource":{"title":"Webhook","properties":{"id":{"type":"integer"},"account_id":{"type":"integer"},"topic":{"type":"string","enum":["shipment","status","account","account_balance","stock"]},"url":{"type":"string","format":"url"}},"type":"object"}}},"paths":{"/accounts/{account_id}/webhooks/{id}":{"put":{"tags":["Webhooks"],"summary":"Actualizar suscripción a webhook","description":"Actualiza la URL de una suscripción a webhook existente.","operationId":"a1c52d244efd7f6dcf87f08b542434a5","parameters":[{"name":"account_id","in":"path","description":"ID de la cuenta","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","description":"ID del webhook","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["url"],"properties":{"url":{"description":"Nueva URL del webhook","type":"string","format":"url"}},"type":"object"}}}},"responses":{"200":{"description":"Webhook actualizado exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResource"}}}},"400":{"description":"Datos inválidos o webhook duplicado"},"403":{"description":"Sin acceso a esta cuenta"},"404":{"description":"Webhook no encontrado"}}}}}}
```

## Eliminar suscripción a webhook

> Elimina una suscripción a webhook y sus intentos fallidos.

```json
{"openapi":"3.0.0","info":{"title":"Zipnova Shipping API V2","version":"2.0.0"},"tags":[{"name":"Webhooks","description":"Gestión de webhooks para notificaciones"}],"servers":[{"url":"https://api.zipnova.com.ar/v2","description":"v2 API - Argentina (AR)"},{"url":"https://api.zipnova.cl/v2","description":"v2 API - Chile (CL)"},{"url":"https://api.zipnova.com.mx/v2","description":"v2 API - México (MX)"}],"security":[{"basicAuth":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","description":"Autenticación básica HTTP utilizando token como nombre de usuario y secret como contraseña","scheme":"basic"},"bearerAuth":{"type":"http","description":"Token de autenticación Bearer OAuth para API V2","bearerFormat":"OAuth","scheme":"bearer"}}},"paths":{"/accounts/{account_id}/webhooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Eliminar suscripción a webhook","description":"Elimina una suscripción a webhook y sus intentos fallidos.","operationId":"fd22849490a752eff9605814679783cc","parameters":[{"name":"account_id","in":"path","description":"ID de la cuenta","required":true,"schema":{"type":"integer"}},{"name":"id","in":"path","description":"ID del webhook","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Webhook eliminado exitosamente"},"403":{"description":"Sin acceso a esta cuenta"},"404":{"description":"Webhook no encontrado"}}}}}}
```