Webhooks

Mailcoach can send a request to your app whenever something happens within Mailcoach.

On this page:

Configuring webhooks

Mailcoach can send a request to your app whenever:

  • a user subscribed
  • a user unsubscribed
  • a campaign was sent
  • a tag was added
  • a tag was removed

You could use these webhooks keep your local database in sync in near-real-time with Mailcoach.

To get started had to the webhooks screen in settings.

screenshot

Securing webhooks

On the details page of a webhook, you can enter a secret.

screenshot

This secret will be used to calculate a signature that will be added in the Signature header to all requests from Mailcoach to your app.

In order to verify that the payload has not been tempered with when you receive the webhook, you can use the payload of the request and your secret to calculate the signature and compare it with the one in the Signature header of the request.

// Payload is the post request body.
// Secret is set in your webhook settings.

$payloadJson = json_encode($payload); 

$signature = hash_hmac('sha256', $payloadJson, $secret);

Keeping a log of all webhook calls

Mailcoach allows you to keep a log of all calls to webhooks.
Note: This feature was added as a non-breaking change. If you want to use this feature make sure you update the Mailcoach config file.

// in config/mailcoach.php
'webhooks' => [
    'logs' => true,
]

After that you will need to publish and run the migrations:

php artisan vendor:publish --tag="mailcoach-migrations"
php artisan migrate

Choosing which events to send

Sometimes you don’t want all types of events to be sent to your webhook. You can select which event types you want on the webhook detail page.
Note: This feature was added as a non-breaking change. If you want to use this feature make sure you update the Mailcoach config file and publish and run the create_webhook_calls_table migration.

// in config/mailcoach.php
'webhooks' => [
    'selectable_event_types_enabled' => false,
]

After that you will need to publish and run the migrations:

php artisan vendor:publish --tag="mailcoach-migrations"
php artisan migrate

Failures

You can disable a webhook if it fails too many consecutive times. Retries do not count.

Note: This feature was added as a non-breaking change. If you want to use this feature make sure you update the Mailcoach config file and publish and run the add_failed_attempts_to_webhook_configurations_table migration.

To configure the maximum number of failures, you can set the maximum_attempts key in the mailcoach config file.
You should also enable the feature by setting the disable_failed_webhooks key in the opt_in_features config file to true.

// in config/mailcoach.php
'webhooks' => [
    'maximum_attempts' => 5,

    'notified_emails' => ['recipient@domain.com'],
],

'opt_in_features' => [
    'disable_failed_webhooks' => true,
]

Payloads

These events will be sent to your webhooks endpoint.

UnconfirmedSubscriberCreatedEvent

If your list uses confirmation, and a new person is added to the list, this event will be sent. At this point the subscriber isn’t confirmed yet.

This is the payload:

  • event: ‘UnconfirmedSubscriberCreatedEvent’
  • email_list_uuid
  • email
  • first_name
  • last_name
  • extra_attributes
  • tags
  • subscribed_at
  • unsubscribed_at
  • created_at
  • updated_at

SubscribedEvent

Will be sent when a subscriber is confirmed

This is the payload:

  • event: ‘SubscribedEvent’
  • email_list_uuid
  • email
  • first_name
  • last_name
  • extra_attributes
  • tags
  • subscribed_at
  • unsubscribed_at
  • created_at
  • updated_at

UnsubscribedEvent

Will be sent when someone unsubscribes

This is the payload:

  • event: ‘UnsubscribedEvent’
  • email_list_uuid
  • email
  • first_name
  • last_name
  • extra_attributes
  • tags
  • subscribed_at
  • unsubscribed_at
  • created_at
  • updated_at

CampaignSentEvent

Will be sent when a campaign has been fully sent

This is the payload:

  • event: ‘CampaignSentEvent’
  • uuid
  • name
  • email_list_uuid
  • email_list
  • template_uuid
  • template
  • from_email
  • from_name
  • status
  • html
  • structured_html
  • email_html
  • webview_html
  • fields
  • utm_tags
  • sent_to_number_of_subscribers
  • segment_class
  • segment_description
  • open_count
  • unique_open_count
  • open_rate
  • click_count
  • unique_click_count
  • click_rate
  • unsubscribe_count
  • unsubscribe_rate
  • bounce_count
  • bounce_rate
  • sent_at
  • statistics_calculated_at
  • scheduled_at
  • summary_mail_sent_at
  • created_at
  • updated_at
Suppressions
Transactional