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 y SMS, los webhooks son particularmente útiles para sincronizar información sobre contactos, suscripciones, campañas y automatizaciones en otras aplicaciones que utilice tu negocio.

Un caso típico de uso es la actualización en tiempo real de un CRM cuando un contacto se suscribe o se da de baja por email o SMS. 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 event_type Descripción
Contacto suscrito por email member_subscribed Se activa cuando un contacto confirma o se suscribe por email en una audiencia.
Baja de contacto por email member_unsubscribed Se activa cuando un contacto se da de baja del canal email.
Contacto vinculado a un grupo member_added_to_group Se activa cuando el contacto se añade a un grupo.
Contacto desvinculado de un grupo member_removed_from_group Se activa cuando el contacto se elimina de un grupo.
Apertura en campaña email member_campaign_opened Se activa cuando un contacto abre una campaña de email.
Click en campaña email member_campaign_clicked Se activa cuando un contacto hace click en un enlace de una campaña de email.
Email entregado member_campaign_delivered Se activa cuando una campaña de email se entrega correctamente.
Rebote en campaña email member_campaign_bounced Se activa cuando un email no puede entregarse.
Denuncia de spam (campaña email) member_campaign_complained Se activa cuando un contacto marca una campaña de email como spam.
Automatización iniciada member_automation_started Se activa cuando un contacto entra en una automatización.
Automatización completada member_automation_completed Se activa cuando un contacto completa una automatización.
Automatización cancelada member_automation_cancelled Se activa cuando se cancela la ejecución de una automatización para un contacto.
Webhook personalizado de automatización custom_automation_step Se activa desde el paso Enviar webhook dentro de una automatización.
Contacto suscrito por SMS member_sms_subscribed Se activa cuando un contacto confirma o se suscribe al canal SMS.
Baja de contacto por SMS member_sms_unsubscribed Se activa cuando un contacto se da de baja del canal SMS.
SMS entregado member_sms_delivered Se activa cuando el proveedor confirma la entrega de un SMS.
Rebote en campaña SMS member_sms_bounced Se activa cuando un SMS falla o no puede entregarse.
Click en campaña SMS member_sms_clicked Se activa cuando un contacto hace click en un enlace trackeado de una campaña SMS.
Respuesta a campaña SMS member_sms_replied Se activa cuando un contacto responde a una campaña SMS.
Estos eventos son webhooks públicos de tu cuenta: EasyMailing envía una solicitud a la URL que configures. No debes confundirlos con el webhook técnico interno de BulkGate, que EasyMailing usa para recibir estados de entrega y respuestas SMS del proveedor y convertirlos en eventos como member_sms_delivered, member_sms_bounced o member_sms_replied.

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:

El formato general se mantiene para email, automatizaciones y SMS: cada elemento incluye id, date, event_type y event_data. En eventos SMS, event_data puede incluir member con phone, first_name, last_name, sms_status, sms_opt_in_at, sms_opt_out_at y sms_opt_in_source; y, cuando aplica, sms_campaign, message_id, url, ip, delivered_at o received_at.


[
  {
    "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.