# 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"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.zipnova.com/envios/recursos-api/cuentas-y-origenes/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.