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, webhooks are particularly useful for synchronizing subscriber and campaign information with other applications your business uses.

A typical use case for webhooks in email marketing is the real-time updating of a CRM when a contact subscribes or unsubscribes from a mailing list. 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:

Event Description
Contact Subscribed Triggered when a contact subscribes to the list.
Contact Unsubscribed Triggered when a contact unsubscribes from the list.
Campaign Opened Triggered when a contact opens an email from a campaign.
Campaign Clicked Triggered when a contact clicks a link within a campaign email.
Campaign Bounced Triggered when an email cannot be delivered (bounce).
Spam Complaint Triggered when a contact marks an email as spam.
Automation Started Triggered when an automation starts.
Automation Completed Triggered when an automation completes.
Automation Canceled Triggered when an automation is canceled.

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:


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