How to create my first webhook

Soporte
  • Updated
Follow

Table of Contents

1. Description and Uses of Webhooks

2. Create a Webhook

3. Webhook Events

4. Payload Example

5. Webhook Secret Verification

1. Description and Uses of Webhooks

Webhooks are tools that allow an application to send information to another in real-time when a specific event occurs. In the context of email marketing and SMS, webhooks are particularly useful for synchronizing contact, subscription, campaign and automation information with other applications your business uses.

A typical use case is updating a CRM in real time when a contact subscribes or unsubscribes by email or SMS. This keeps the contact database always up-to-date without manual intervention.

2. Create a Webhook

To create a webhook in EasyMailing, follow these steps:

  1. Access the settings and select "Webhooks" from the menu.
  2. In the dropdown menu, select "Webhooks" to manage your existing webhooks or create a new one.

Webhook Fields

  • Title: Identifying name of the webhook.
  • Audience: The audience for which events will trigger the webhook.
  • Event Types: Specific events that will trigger the webhook.
  • URL: The address to which event data will be sent.
  • Secret: Secret key for authenticating requests.
  • Active: Status of the webhook (active/inactive).

Event Types

For each webhook created, you can select multiple events that will trigger the webhook. The available event types are described below:

Evento event_type Descripción
Contact subscribed by email member_subscribed Triggered when a contact confirms or subscribes by email in an audience.
Contact unsubscribed from email member_unsubscribed Triggered when a contact unsubscribes from the email channel.
Added contact to a group member_added_to_group Triggered when the contact is added to a group.
Removed contact from a group member_removed_from_group Triggered when the contact is removed from a group.
Email campaign opened member_campaign_opened Triggered when a contact opens an email campaign.
Email campaign clicked member_campaign_clicked Triggered when a contact clicks a link in an email campaign.
Email delivered member_campaign_delivered Triggered when an email campaign is delivered successfully.
Email campaign bounced member_campaign_bounced Triggered when an email cannot be delivered.
Email campaign complained member_campaign_complained Triggered when a contact marks an email campaign as spam.
Automation started member_automation_started Triggered when a contact enters an automation.
Automation completed member_automation_completed Triggered when a contact completes an automation.
Automation cancelled member_automation_cancelled Triggered when an automation execution is cancelled for a contact.
Custom automation step webhook custom_automation_step Triggered from the Send webhook step inside an automation.
Contact subscribed by SMS member_sms_subscribed Triggered when a contact confirms or subscribes to the SMS channel.
Contact unsubscribed from SMS member_sms_unsubscribed Triggered when a contact unsubscribes from the SMS channel.
SMS delivered member_sms_delivered Triggered when the provider confirms SMS delivery.
SMS campaign bounced member_sms_bounced Triggered when an SMS fails or cannot be delivered.
SMS campaign clicked member_sms_clicked Triggered when a contact clicks a tracked link in an SMS campaign.
SMS campaign replied member_sms_replied Triggered when a contact replies to an SMS campaign.
These events are public webhooks for your account: EasyMailing sends a request to the URL you configure. Do not confuse them with the internal technical BulkGate webhook, which EasyMailing uses to receive SMS delivery statuses and replies from the provider and convert them into events such as member_sms_delivered, member_sms_bounced or member_sms_replied.

3. Webhook Events

Webhook events record all requests made to the configured URL, along with relevant data. These records are useful for developers to debug and verify that webhook calls are working correctly.

Data recorded for each event includes:

Field Description
Response Code The HTTP response code of the request.
Date Date and time of the request.
Success Indicator of whether the request was successful.
Attempts Number of attempts made for the request.
Payload The data sent in the request.
Response Body The body of the received response.

Each event can have multiple calls; for example, an unsubscribe and a campaign open can be recorded in the same event.

4. Payload Example

Below is an example of payload code:

The general format is the same for email, automations and SMS: each item includes id, date, event_type and event_data. For SMS events, event_data can include member with phone, first_name, last_name, sms_status, sms_opt_in_at, sms_opt_out_at and sms_opt_in_source; and, when applicable, sms_campaign, message_id, url, ip, delivered_at or 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": "user@company.com",
        "status": "suscriber.status.confirmed",
        "source": "suscriber.source.webform",
        "groups": [
          {
            "id": "d7a83bf3-4891-4fe9-a39b-c827fdf82fde",
            "title": "Advertising"
          }
        ],
        "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": "I accept receiving commercial emails"
              }
            },
            {
              "id": "c6e702de-0273-4c8e-a24a-da4a8b7241ac",
              "translations": {
                "es_ES": "I accept receiving informative communications"
              }
            }
          ]
        },
        "location": null,
        "suscribed_at": null,
        "unsuscribed_at": null
      },
      "automation": {
        "id": "9",
        "title": "Advertising",
        "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": "test",
        "type": "popup"
      },
      "member": {
        "id": "5e8bdd2d-385b-47dd-beb4-2ee8ea11cb9b",
        "audience_id": "419eb38e-62fd-454e-98a7-c8dd5e9752dd",
        "email": "user@company.com",
        "status": "suscriber.status.confirmed",
        "source": "suscriber.source.webform",
        "groups": [
          {
            "id": "d7a83bf3-4891-4fe9-a39b-c827fdf82fde",
            "title": "Advertising"
          }
        ],
        "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": "I accept receiving commercial emails"
              }
            },
            {
              "id": "c6e702de-0273-4c8e-a24a-da4a8b7241ac",
              "translations": {
                "es_ES": "I accept receiving informative communications"
              }
            }
          ]
        },
        "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": "Advertising"
          }
        ],
        "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": "I accept receiving commercial emails"
              }
            },
            {
              "id": "c6e702de-0273-4c8e-a24a-da4a8b7241ac",
              "translations": {
                "es_ES": "I accept receiving informative communications"
              }
            }
          ]
        },
        "location": null,
        "suscribed_at": null,
        "unsuscribed_at": null
      },
      "automation": {
        "id": "9",
        "title": "Advertising",
        "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": "user@company.com",
        "status": "suscriber.status.confirmed",
        "source": "suscriber.source.webform",
        "groups": [
          {
            "id": "d7a83bf3-4891-4fe9-a39b-c827fdf82fde",
            "title": "Advertising"
          }
        ],
        "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": "I accept receiving informative communications"
              }
            }
          ]
        },
        "location": null,
        "suscribed_at": null,
        "unsuscribed_at": null
      },
      "automation": {
        "id": "9",
        "title": "Advertising",
        "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": "test",
        "type": "popup"
      },
      "member": {
        "id": "123e95d2-2a9c-4247-89d8-3c0cfedae868",
        "audience_id": "419eb38e-62fd-454e-98a7-c8dd5e9752dd",
        "email": "user@company.com",
        "status": "suscriber.status.confirmed",
        "source": "suscriber.source.webform",
        "groups": [
          {
            "id": "d7a83bf3-4891-4fe9-a39b-c827fdf82fde",
            "title": "Advertising"
          }
        ],
        "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": "I accept receiving informative communications"
              }
            }
          ]
        },
        "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": "Advertising"
          }
        ],
        "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": "I accept receiving informative communications"
              }
            }
          ]
        },
        "location": null,
        "suscribed_at": null,
        "unsuscribed_at": null
      },
      "automation": {
        "id": "9",
        "title": "Advertising",
        "status": "automation.queue.status.completed"
      },
      "trigger": "trigger.contact.added.to.group",
      "status": "automation.queue.status.completed"
    }
  }
]

5. Webhook Secret Verification

To ensure that requests to your webhook URL are legitimate and originate from EasyMailing, a secret is used which is included in the request headers.

When you receive a webhook request, you can verify its authenticity by creating an HMAC signature using the request body and the shared secret, and comparing it with the Easymailing-Webhook-Signature header sent in the request.

Example PHP code to verify the signature:


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

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

if (hash_equals($computedSignature, $signature)) {
    // The request is valid
    http_response_code(200);
    echo 'Signature verified';
} else {
    // The request is not valid
    http_response_code(403);
    echo 'Invalid signature';
}

Related articles

Comments

0 comments

Please sign in to leave a comment.