Migrar Webhooks Vesion1 a Version3
La migración de la versión de webhooks en una implementación de los servicios de Syncfy es relativamente sencilla.
Eventos V1 vs V3
Una de las mejoras que se integran en la V3 de los webhooks es la posibilidad de suscribir nuevos eventos webhook.
En la V1 de webhooks contamos con los eventos:
credential_create: Una nueva credencial fue creada
{
"endpoints": {
"credential": [
"/v1/credentials/5e793889ea4c5165d46f9811"
]
},
"event": "credential_create",
"id_credential": "5e793889ea4c5165d46f9811",
"id_external": "IXS7607092R5",
"id_job": "5e793889b783081dd61de29c",
"id_job_uuid": "5e793889b783081dd61de29b",
"id_site": "5da784f1f9de2a06483abec1",
"id_site_organization": "56cf4ff5784806152c8b4567",
"id_site_organization_type": "56cf4f5b784806cf028b4569",
"id_user": "5e751d54d0510472295413b3",
"is_executing": 1
}
credential_update: Una credencial existente fue actualizada
{
"endpoints": {
"credential": [
"/v1/credentials/5e793889ea4c5165d46f9811"
]
},
"event": "credential_update",
"id_credential": "5e793889ea4c5165d46f9811",
"id_external": "IXS7607092R5",
"id_job": "5e793889b783081dd61de29c",
"id_job_uuid": "5e793889b783081dd61de29b",
"id_site": "5da784f1f9de2a06483abec1",
"id_site_organization": "56cf4ff5784806152c8b4567",
"id_site_organization_type": "56cf4f5b784806cf028b4569",
"id_user": "5e751d54d0510472295413b3",
"is_executing": 1
}
refresh: Información de una credencial existente fue agregada o actualizada.
{
"endpoints": {
"accounts": [
"/v1/accounts?id_credential=5e793889ea4c5165d46f9811&limit=5000&skip=0&wbhk=1"
],
"attachments": [
"/v1/attachments/export?id_credential=5e793889ea4c5165d46f9811&limit=5000&skip=0&wbhk=1",
"/v1/attachments/export?id_credential=5e793889ea4c5165d46f9811&limit=5000&skip=5000&wbhk=1",
"/v1/attachments/export?id_credential=5e793889ea4c5165d46f9811&limit=5000&skip=10000&wbhk=1"
],
"credential": [
"/v1/credentials/5e793889ea4c5165d46f9811"
],
"transactions": [
"/v1/transactions?id_credential=5e793889ea4c5165d46f9811&limit=5000&skip=0&wbhk=1",
"/v1/transactions?id_credential=5e793889ea4c5165d46f9811&limit=5000&skip=5000&wbhk=1",
"/v1/transactions?id_credential=5e793889ea4c5165d46f9811&limit=5000&skip=10000&wbhk=1"
]
},
"event": "refresh",
"id_credential": "5e793889ea4c5165d46f9811",
"id_external": "IXS7607092R5",
"id_job": "5e793889b783081dd61de29c",
"id_job_uuid": "5e793889b783081dd61de29b",
"id_site": "5da784f1f9de2a06483abec1",
"id_site_organization": "56cf4ff5784806152c8b4567",
"id_site_organization_type": "56cf4f5b784806cf028b4569",
"id_user": "5e751d54d0510472295413b3"
}
documents_completed: La descarga de un documento nuevo ha sido finalizada.
{
"event":"documents_completed",
"id_user":"61c7c427e21d3e5b360a2110",
"id_external":"616e2f29-753f-4109-bc29-c932173403fc",
"id_job":"6254c6acc818be432d24cda7",
"id_job_uuid":"6254c6acc818be432d24cda8",
"id_site":"59aefe28056f29793a58c092",
"id_site_organization":"56cf4ff5784806152c8b4568",
"id_site_organization_type":"56cf4f5b784806cf028b4569",
"uuid":"d4d219a1-cb0c-49a0-beb4-213fa38166ca",
"endpoints":{
"documents":[
"/v1/webhooks/events/d4d219a1-cb0c-49a0-beb4-213fa38166ca/documents?limit=1000&skip=0"
],
"documents_zip":[
"/v1/webhooks/events/d4d219a1-cb0c-49a0-beb4-213fa38166ca/documents/zip?limit=1000&skip=0"
],
"documents_json":[
"/v1/webhooks/events/d4d219a1-cb0c-49a0-beb4-213fa38166ca/documents/json?limit=1000&skip=0"
]
}
}
En la V3 contamos con los mismos eventos de la V1, aquí solo cambia el nombre del evento y el body del request.
credentials.created: Una nueva credencial fue creada
{
"rid": "e194e79e-1b26-405e-b05f-abc00e9371dc",
"events": [
{
"header": {
"event": {
"eid": "d7b5e6b3-19c4-44d6-a52a-c7a5450f963e",
"name": "credentials.created",
"at": "2022-05-11 21:46:36.453219+0000",
"version": "3.1"
},
"user": {
"id_user": "624234673365216f2138a959",
"id_external": "pman-test-unit00",
"id_environment": "574894bf7848066d138b4570"
}
},
"payload": {
"event": "credential_create",
"id_job": "627c2ebaa229af1a88720deb",
"id_job_uuid": "627c2ebaa229af1a88720dea",
"id_credential": "627c2ebabcc9f070eb5a5a96",
"id_user": "624234673365216f2138a959",
"id_external": "pman-test-unit00",
"id_site": "56cf5728784806f72b8b4568",
"id_site_organization": "56cf4ff5784806152c8b4567",
"id_site_organization_type": "56cf4f5b784806cf028b4568",
"is_executing": 1,
"endpoints": {
"credential": [
"/v1/credentials/627c2ebabcc9f070eb5a5a96"
]
}
}
}
]
}
credentials.updated: Una credencial existente fue actualizada
{
"rid": "ca950a74-4a42-4ab0-a4eb-df85b0203584",
"events": [
{
"header": {
"event": {
"eid": "65b103d8-471c-41d5-822a-aad0dc46bfdd",
"name": "credentials.updated",
"at": "2022-05-11 21:46:43.591671+0000",
"version": "3.1"
},
"user": {
"id_user": "624234673365216f2138a959",
"id_external": "pman-test-unit00",
"id_environment": "574894bf7848066d138b4570"
}
},
"payload": {
"event": "credential_update",
"id_job": "627c2ebaa229af1a88720deb",
"id_job_uuid": "627c2ebaa229af1a88720dea",
"id_credential": "627c2ebabcc9f070eb5a5a96",
"id_user": "624234673365216f2138a959",
"id_external": "pman-test-unit00",
"id_site": "56cf5728784806f72b8b4568",
"id_site_organization": "56cf4ff5784806152c8b4567",
"id_site_organization_type": "56cf4f5b784806cf028b4568",
"is_executing": 1,
"endpoints": {
"credential": [
"/v1/credentials/627c2ebabcc9f070eb5a5a96"
]
}
}
}
]
}
credentials.refreshed: Información de una credencial existente fue agregada o actualizada.
{
"rid": "5076fcd2-5f46-4efb-9c4b-6abaa1520491",
"events": [
{
"header": {
"event": {
"eid": "7d2c7871-65e7-47f9-8d30-080c2f800e7c",
"name": "credentials.refreshed",
"at": "2022-05-11 21:47:02.786681+0000",
"version": "3.1"
},
"user": {
"id_user": "624234673365216f2138a959",
"id_external": "pman-test-unit00",
"id_environment": "574894bf7848066d138b4570"
}
},
"payload": {
"event": "refresh",
"id_job": "627c2ebaa229af1a88720deb",
"id_job_uuid": "627c2ebaa229af1a88720dea",
"id_credential": "627c2ebabcc9f070eb5a5a96",
"id_user": "624234673365216f2138a959",
"id_external": "pman-test-unit00",
"id_site": "56cf5728784806f72b8b4568",
"id_site_organization": "56cf4ff5784806152c8b4567",
"id_site_organization_type": "56cf4f5b784806cf028b4568",
"endpoints": {
"credential": [
"/v1/credentials/627c2ebabcc9f070eb5a5a96"
],
"accounts": [
"/v1/accounts?id_credential=627c2ebabcc9f070eb5a5a96&dt_refresh_from=1643412016&dt_refresh_to=1652280371&limit=5000&skip=0&wbhk=1"
],
"transactions": [
"/v1/transactions?id_credential=627c2ebabcc9f070eb5a5a96&dt_refresh_from=1643412016&dt_refresh_to=1652280371&limit=5000&skip=0&wbhk=1"
]
}
}
}
]
}
Adicionalmente, se puede suscribir un evento nuevo para credenciales:
credentials.deleted: Una credencial existente fue eliminada.
{
"rid": "6bed7e45-cbc4-4bbd-ad0b-c07269d8e857",
"events": [
{
"header": {
"event": {
"eid": "be0cd7f8-e614-4f5b-bb33-298e920bcf77",
"name": "credentials.deleted",
"at": "2022-05-11 21:54:18.247465+0000",
"version": "3.1"
},
"user": {
"id_user": "624234673365216f2138a959",
"id_external": "pman-test-unit00",
"id_environment": "574894bf7848066d138b4570"
}
},
"payload": {
"id_credential": "627c2ebabcc9f070eb5a5a96"
}
}
]
}
En la V3 de los webhook también podemos suscribir eventos nuevos para documentos:
documents.completed: La descarga de un documento nuevo ha sido finalizada.
{
"rid": "54181c36-8aa3-4aa4-8c69-a7c1173a3309",
"events": [
{
"header": {
"event": {
"eid": "0c76f3cd-dd86-4e61-b82e-7436d1534e06",
"name": "documents.completed",
"at": "2022-05-11 23:55:26.304080+0000",
"version": "3.1"
},
"user": {
"id_user": "6228fb14233600433679a6ef",
"id_external": "ACM1306103E7",
"id_environment": "574894bf7848066d138b4571"
}
},
"payload": {
"id_job": "627c4cce48966b217d4658e4",
"id_job_uuid": "627c4cce48966b217d4658e5",
"id_site": "59aefe28056f29793a58c092",
"id_site_organization": "56cf4ff5784806152c8b4568",
"id_site_organization_type": "56cf4f5b784806cf028b4569",
"endpoints": [
"/v1/documents?id_job_webhook=627c4cee3566547974827192"
]
}
}
]
}
documents.success: La descarga de un documento nuevo ha sido finalizada con éxito.
{
"rid": "54181c36-8aa3-4aa4-8c69-a7c1173a3309",
"events": [
{
"header": {
"event": {
"eid": "0c76f3cd-dd86-4e61-b82e-7436d1534e06",
"name": "documents.success",
"at": "2022-05-11 23:55:26.304080+0000",
"version": "3.1"
},
"user": {
"id_user": "6228fb14233600433679a6ef",
"id_external": "ACO1306103J7",
"id_environment": "574894bf7848066d138b4571"
}
},
"payload": {
"id_job": "627c4cce48966b217d4658e4",
"id_job_uuid": "627c4cce48966b217d4658e5",
"id_site": "59aefe28056f29793a58c092",
"id_site_organization": "56cf4ff5784806152c8b4568",
"id_site_organization_type": "56cf4f5b784806cf028b4569",
"endpoints": [
"/v1/documents?id_job_webhook=627c4cee3566547974827192"
]
}
}
]
}
documents.failed: La descarga de un documento ha fallado.
{
"rid": "54181c36-8aa3-4aa4-8c69-a7c1173a3309",
"events": [
{
"header": {
"event": {
"eid": "0c76f3cd-dd86-4e61-b82e-7436d1534e06",
"name": "documents.failed",
"at": "2022-05-11 23:55:26.304080+0000",
},
"user": {
"id_user": "6228fb14233600433679a6ef",
"id_external": "ACO1306103J7",
"id_environment": "574894bf7848066d138b4571"
}
},
"payload": {
"id_job": "627c4cce48966b217d4658e4",
"id_job_uuid": "627c4cce48966b217d4658e5",
"id_site": "59aefe28056f29793a58c092",
"id_site_organization": "56cf4ff5784806152c8b4568",
"id_site_organization_type": "56cf4f5b784806cf028b4569",
"endpoints": [
"/v1/documents?id_job_webhook=627c4cee3566547974827192"
]
}
}
]
}
La diferencia entre "documents.success" y "documents.completed" es que el completed puede tener fallos y el success solo los exitosos.
Ejemplo:
Si una descarga guarda 3 documentos, y 2 fallan, el sucess solo tiene 2, y el completed tiene 3.
La principal diferencia entre los eventos de los Webhooks V1 y V3 es la estructura del payload.
Creación de Webhooks V1 vs V3
Los Webhooks V1 se gestionan a través de peticiones al API, especificamente al endpoint /v1/webhooks/
- GET - Obtiene los webhooks registrados.
- POST - Crea un Webhook nuevo
- DELETE - Elimina un webhook en especifico.
Por el contrario los Webhook V3 se gestionan a través de la interfaz gráfica del dashboard de Syncfy, en la sección de Webhooks.
- Entrar a www.syncfy.com
- Acceder a la secciónde Developers
- Iniciar sesión.
- Dirigirse al modulo de webhooks.
- Gestionar nuestros webhooks.
