Cómo crear mi primer webhook

Soporte
  • Actualización
Seguir

Índice de contenidos

1. Descripción y Usos de los Webhooks

2. Crear un Webhook

3. Eventos de Webhook

4. Ejemplo de Payload

5. Verificación del Secreto del Webhook

1. Descripción y Usos de los Webhooks

Los webhooks son herramientas que permiten que una aplicación envíe información a otra en tiempo real cuando ocurre un evento específico. En el contexto del email marketing, los webhooks son particularmente útiles para sincronizar información sobre los suscriptores y las campañas en otras aplicaciones que utilice tu negocio.

Un caso típico de uso de los webhooks en email marketing es la actualización en tiempo real de un CRM cuando un contacto se suscribe o se da de baja de una lista de correo. Esto permite mantener la base de datos de contactos siempre actualizada sin intervención manual.

2. Crear un Webhook

Para crear un webhook en EasyMailing, sigue estos pasos:

  1. Accede a los ajustes y selecciona "Webhooks" en el menú.
  2. En el menú desplegable, selecciona "Webhooks" para gestionar tus webhooks existentes o crear uno nuevo.

Campos del Webhook

  • Título: Nombre identificativo del webhook.
  • Audiencia: La audiencia en la que los eventos dispararán el webhook.
  • Tipos de eventos: Eventos específicos que activarán el webhook.
  • URL: La dirección a la cual se enviarán los datos del evento.
  • Secreto: Clave secreta para la autenticación de las solicitudes.
  • Activo: Estado del webhook (activo/inactivo).

Tipos de Eventos

En cada webhook creado, puedes seleccionar múltiples eventos que activarán el webhook. A continuación, se describen los tipos de eventos disponibles:

Evento Descripción
Contacto suscrito Se activa cuando un contacto se suscribe a la lista.
Baja de contacto Se activa cuando un contacto se da de baja de la lista.
Apertura en campaña Se activa cuando un contacto abre un correo de una campaña.
Clic en campaña Se activa cuando un contacto hace clic en un enlace dentro de un correo de una campaña.
Rebote en campaña Se activa cuando un correo no puede ser entregado (rebote).
Denuncia de spam Se activa cuando un contacto denuncia un correo como spam.
Automatización iniciada Se activa cuando se inicia una automatización.
Automatización completada Se activa cuando una automatización se completa.
Automatización cancelada Se activa cuando una automatización se cancela.

3. Eventos de Webhook

Los eventos de webhook registran todas las solicitudes realizadas a la URL configurada, junto con los datos relevantes. Estos registros son útiles para que los desarrolladores puedan hacer debug y verificar que las llamadas a los webhooks funcionan correctamente.

Los datos que se registran para cada evento incluyen:

Campo Descripción
Código de respuesta El código HTTP de respuesta de la solicitud.
Fecha Fecha y hora de la solicitud.
Éxito Indicador de si la solicitud fue exitosa.
Intentos Número de intentos realizados para la solicitud.
Payload Los datos enviados en la solicitud.
Response body El cuerpo de la respuesta recibida.

En cada evento puede haber múltiples llamadas, por ejemplo, una baja de contacto y una apertura en campaña pueden ser registradas en el mismo evento.

4. Ejemplo de Payload

A continuación, se muestra un ejemplo de código de payload:


[
  {
    "id": "d66e27a7-c41b-49e4-942a-bda6f07e3320",
    "date": "2024-05-23T20:36:08+00:00",
    "event_type": "member_automation_started",
    "event_data": {
      "member": {
        "id": "5e8bdd2d-385b-47dd-beb4-2ee8ea11cb9b",
        "audience_id": "419eb38e-62fd-454e-98a7-c8dd5e9752dd",
        "email": "usuario@empresa.com",
        "status": "suscriber.status.confirmed",
        "source": "suscriber.source.webform",
        "groups": [
          {
            "id": "d7a83bf3-4891-4fe9-a39b-c827fdf82fde",
            "title": "Publicidad"
          }
        ],
        "custom_fields": [
          {
            "list_field_id": "32f651b9-ddf4-431e-9643-9773052a588c",
            "value": null
          },
          {
            "list_field_id": "6ed14a07-35e6-48d5-98eb-d2acdbd31d7b",
            "value": "pepito"
          },
          {
            "list_field_id": "87825e33-8611-49d3-b303-f482df9ff60e",
            "value": "perez"
          },
          {
            "list_field_id": "d08af061-ca23-4f87-9761-b896afb175c3",
            "value": true
          },
          {
            "list_field_id": "c5f79359-9f8f-477a-8ba2-4cd3ce448495",
            "value": null
          }
        ],
        "member_consent": {
          "ip": "10.6.0.1",
          "consent_at": "2024-05-23T20:36:07+00:00",
          "treatment_purposes": [
            {
              "id": "2ad352b8-7915-47d3-bfef-9adab2326d8b",
              "translations": {
                "es_ES": "Acepto el env\u00edo  de emails comerciales"
              }
            },
            {
              "id": "c6e702de-0273-4c8e-a24a-da4a8b7241ac",
              "translations": {
                "es_ES": "Acepto el env\u00edo de comunicaciones informativas"
              }
            }
          ]
        },
        "location": null,
        "suscribed_at": null,
        "unsuscribed_at": null
      },
      "automation": {
        "id": "9",
        "title": "Publicidad",
        "status": "automation.queue.status.queued"
      },
      "trigger": "trigger.contact.added.to.group",
      "status": "automation.queue.status.queued"
    }
  },
  {
    "id": "0dc29671-5213-4fe4-aeee-6ebf7c25bdf3",
    "date": "2024-05-23T20:36:09+00:00",
    "event_type": "member_subscribed",
    "event_data": {
      "source": "suscriber.source.webform",
      "subscription_form": {
        "id": "0ad52971-6fc5-421a-ad18-07940f05500f",
        "title": "prueba",
        "type": "popup"
      },
      "member": {
        "id": "5e8bdd2d-385b-47dd-beb4-2ee8ea11cb9b",
        "audience_id": "419eb38e-62fd-454e-98a7-c8dd5e9752dd",
        "email": "usuario@empresa.com",
        "status": "suscriber.status.confirmed",
        "source": "suscriber.source.webform",
        "groups": [
          {
            "id": "d7a83bf3-4891-4fe9-a39b-c827fdf82fde",
            "title": "Publicidad"
          }
        ],
        "custom_fields": [
          {
            "list_field_id": "32f651b9-ddf4-431e-9643-9773052a588c",
            "value": null
          },
          {
            "list_field_id": "6ed14a07-35e6-48d5-98eb-d2acdbd31d7b",
            "value": "Peter"
          },
          {
            "list_field_id": "87825e33-8611-49d3-b303-f482df9ff60e",
            "value": "Smith"
          },
          {
            "list_field_id": "d08af061-ca23-4f87-9761-b896afb175c3",
            "value": true
          },
          {
            "list_field_id": "c5f79359-9f8f-477a-8ba2-4cd3ce448495",
            "value": null
          }
        ],
        "member_consent": {
          "ip": "10.6.0.1",
          "consent_at": "2024-05-23T20:36:07+00:00",
          "treatment_purposes": [
            {
              "id": "2ad352b8-7915-47d3-bfef-9adab2326d8b",
              "translations": {
                "es_ES": "Acepto el envío  de emails comerciales"
              }
            },
            {
              "id": "c6e702de-0273-4c8e-a24a-da4a8b7241ac",
              "translations": {
                "es_ES": "Acepto el env\u00edo de comunicaciones informativas"
              }
            }
          ]
        },
        "location": null,
        "suscribed_at": "2024-05-23T20:36:08+00:00",
        "unsuscribed_at": null
      }
    }
  },
  {
    "id": "c708f563-fe3d-4375-b276-ce4aefc829f1",
    "date": "2024-05-23T20:36:09+00:00",
    "event_type": "member_automation_completed",
    "event_data": {
      "member": {
        "id": "5e8bdd2d-385b-47dd-beb4-2ee8ea11cb9b",
        "audience_id": "419eb38e-62fd-454e-98a7-c8dd5e9752dd",
        "email": "123131232@paquito.com",
        "status": "suscriber.status.confirmed",
        "source": "suscriber.source.webform",
        "groups": [
          {
            "id": "d7a83bf3-4891-4fe9-a39b-c827fdf82fde",
            "title": "Publicidad"
          }
        ],
        "custom_fields": [
          {
            "list_field_id": "32f651b9-ddf4-431e-9643-9773052a588c",
            "value": null
          },
          {
            "list_field_id": "6ed14a07-35e6-48d5-98eb-d2acdbd31d7b",
            "value": "Peter"
          },
          {
            "list_field_id": "87825e33-8611-49d3-b303-f482df9ff60e",
            "value": "Smith"
          },
          {
            "list_field_id": "d08af061-ca23-4f87-9761-b896afb175c3",
            "value": true
          },
          {
            "list_field_id": "c5f79359-9f8f-477a-8ba2-4cd3ce448495",
            "value": null
          }
        ],
        "member_consent": {
          "ip": "10.6.0.1",
          "consent_at": "2024-05-23T20:36:07+00:00",
          "treatment_purposes": [
            {
              "id": "2ad352b8-7915-47d3-bfef-9adab2326d8b",
              "translations": {
                "es_ES": "Acepto el envío  de emails comerciales"
              }
            },
            {
              "id": "c6e702de-0273-4c8e-a24a-da4a8b7241ac",
              "translations": {
                "es_ES": "Acepto el env\u00edo de comunicaciones informativas"
              }
            }
          ]
        },
        "location": null,
        "suscribed_at": null,
        "unsuscribed_at": null
      },
      "automation": {
        "id": "9",
        "title": "Publicidad",
        "status": "automation.queue.status.completed"
      },
      "trigger": "trigger.contact.added.to.group",
      "status": "automation.queue.status.completed"
    }
  },
  {
    "id": "e6756888-caae-4df6-a23e-07b95b289d25",
    "date": "2024-05-23T20:36:23+00:00",
    "event_type": "member_automation_started",
    "event_data": {
      "member": {
        "id": "123e95d2-2a9c-4247-89d8-3c0cfedae868",
        "audience_id": "419eb38e-62fd-454e-98a7-c8dd5e9752dd",
        "email": "usuario@empresa.com",
        "status": "suscriber.status.confirmed",
        "source": "suscriber.source.webform",
        "groups": [
          {
            "id": "d7a83bf3-4891-4fe9-a39b-c827fdf82fde",
            "title": "Publicidad"
          }
        ],
        "custom_fields": [
          {
            "list_field_id": "32f651b9-ddf4-431e-9643-9773052a588c",
            "value": null
          },
          {
            "list_field_id": "6ed14a07-35e6-48d5-98eb-d2acdbd31d7b",
            "value": "dgdfg"
          },
          {
            "list_field_id": "87825e33-8611-49d3-b303-f482df9ff60e",
            "value": "perez"
          },
          {
            "list_field_id": "d08af061-ca23-4f87-9761-b896afb175c3",
            "value": true
          },
          {
            "list_field_id": "c5f79359-9f8f-477a-8ba2-4cd3ce448495",
            "value": null
          }
        ],
        "member_consent": {
          "ip": "10.6.0.1",
          "consent_at": "2024-05-23T20:36:22+00:00",
          "treatment_purposes": [
            {
              "id": "c6e702de-0273-4c8e-a24a-da4a8b7241ac",
              "translations": {
                "es_ES": "Acepto el env\u00edo de comunicaciones informativas"
              }
            }
          ]
        },
        "location": null,
        "suscribed_at": null,
        "unsuscribed_at": null
      },
      "automation": {
        "id": "9",
        "title": "Publicidad",
        "status": "automation.queue.status.queued"
      },
      "trigger": "trigger.contact.added.to.group",
      "status": "automation.queue.status.queued"
    }
  },
  {
    "id": "01824451-1975-41ec-ae60-5af64b44c1d4",
    "date": "2024-05-23T20:36:23+00:00",
    "event_type": "member_subscribed",
    "event_data": {
      "source": "suscriber.source.webform",
      "subscription_form": {
        "id": "0ad52971-6fc5-421a-ad18-07940f05500f",
        "title": "prueba",
        "type": "popup"
      },
      "member": {
        "id": "123e95d2-2a9c-4247-89d8-3c0cfedae868",
        "audience_id": "419eb38e-62fd-454e-98a7-c8dd5e9752dd",
        "email": "usuario@empresa.com",
        "status": "suscriber.status.confirmed",
        "source": "suscriber.source.webform",
        "groups": [
          {
            "id": "d7a83bf3-4891-4fe9-a39b-c827fdf82fde",
            "title": "Publicidad"
          }
        ],
        "custom_fields": [
          {
            "list_field_id": "32f651b9-ddf4-431e-9643-9773052a588c",
            "value": null
          },
          {
            "list_field_id": "6ed14a07-35e6-48d5-98eb-d2acdbd31d7b",
            "value": "dgdfg"
          },
          {
            "list_field_id": "87825e33-8611-49d3-b303-f482df9ff60e",
            "value": "perez"
          },
          {
            "list_field_id": "d08af061-ca23-4f87-9761-b896afb175c3",
            "value": true
          },
          {
            "list_field_id": "c5f79359-9f8f-477a-8ba2-4cd3ce448495",
            "value": null
          }
        ],
        "member_consent": {
          "ip": "10.6.0.1",
          "consent_at": "2024-05-23T20:36:22+00:00",
          "treatment_purposes": [
            {
              "id": "c6e702de-0273-4c8e-a24a-da4a8b7241ac",
              "translations": {
                "es_ES": "Acepto el env\u00edo de comunicaciones informativas"
              }
            }
          ]
        },
        "location": null,
        "suscribed_at": "2024-05-23T20:36:23+00:00",
        "unsuscribed_at": null
      }
    }
  },
  {
    "id": "2b90230e-4f5a-457b-806d-e2a787f5dc49",
    "date": "2024-05-23T20:36:24+00:00",
    "event_type": "member_automation_completed",
    "event_data": {
      "member": {
        "id": "123e95d2-2a9c-4247-89d8-3c0cfedae868",
        "audience_id": "419eb38e-62fd-454e-98a7-c8dd5e9752dd",
        "email": "44444@paquito.com",
        "status": "suscriber.status.confirmed",
        "source": "suscriber.source.webform",
        "groups": [
          {
            "id": "d7a83bf3-4891-4fe9-a39b-c827fdf82fde",
            "title": "Publicidad"
          }
        ],
        "custom_fields": [
          {
            "list_field_id": "32f651b9-ddf4-431e-9643-9773052a588c",
            "value": null
          },
          {
            "list_field_id": "6ed14a07-35e6-48d5-98eb-d2acdbd31d7b",
            "value": "dgdfg"
          },
          {
            "list_field_id": "87825e33-8611-49d3-b303-f482df9ff60e",
            "value": "perez"
          },
          {
            "list_field_id": "d08af061-ca23-4f87-9761-b896afb175c3",
            "value": true
          },
          {
            "list_field_id": "c5f79359-9f8f-477a-8ba2-4cd3ce448495",
            "value": null
          }
        ],
        "member_consent": {
          "ip": "10.6.0.1",
          "consent_at": "2024-05-23T20:36:22+00:00",
          "treatment_purposes": [
            {
              "id": "c6e702de-0273-4c8e-a24a-da4a8b7241ac",
              "translations": {
                "es_ES": "Acepto el env\u00edo de comunicaciones informativas"
              }
            }
          ]
        },
        "location": null,
        "suscribed_at": null,
        "unsuscribed_at": null
      },
      "automation": {
        "id": "9",
        "title": "Publicidad",
        "status": "automation.queue.status.completed"
      },
      "trigger": "trigger.contact.added.to.group",
      "status": "automation.queue.status.completed"
    }
  }
]

5. Verificación del Secreto del Webhook

Para asegurar que las peticiones a tu URL de webhook son legítimas y provienen de EasyMailing, se utiliza un secreto (secret) que se incluye en las cabeceras de la solicitud.

Cuando recibas una solicitud de webhook, puedes verificar su autenticidad creando una firma HMAC usando el cuerpo de la solicitud y el secreto compartido, y comparándola con la cabecera Easymailing-Webhook-Signature enviada en la solicitud.

Ejemplo de código en PHP para verificar la firma:



$secret = 'tu_secreto_webhook';
$body = file_get_contents('php://input');
$signature = $_SERVER['HTTP_EASYMAILING_WEBHOOK_SIGNATURE'];

$computedSignature = hash_hmac('sha256', $body, $secret);

if (hash_equals($computedSignature, $signature)) {
    // La petición es válida
    http_response_code(200);
    echo 'Firma verificada';
} else {
    // La petición no es válida
    http_response_code(403);
    echo 'Firma no válida';
}

Artículos relacionados

Comentarios

0 comentarios

Inicie sesión para dejar un comentario.