Webhooks

Webhooks allow you to receive all information about your deliverability and activities within your account almost in real-time.

Event types

The event data you receive includes:

Sending events:

• Delivery

• Bounce

• Unsubscribe

• Spam Complaint

• Reject

• Soft Bounce

• Suspension

• Open

• Click

Activity Log events (available for enterprise only):

• User updated API token permissions

• User updated the email address or password

• User invited someone else to the account

• And more

To find out more about the sending event specifics, check the Statuses and Events article.

How to set up webhooks

1

Navigate to Settings → Webhooks and click the Create New Webhook button.

2

Enter a valid Webhook URL. Use a password and username as an extra security layer with basic authorization to prevent others from sending information to that endpoint. You can also use a token as a query parameter.

3

Choose the Payload format (JSON or JSON Lines).

4

Select the webhooks area (Activity Log or Email Sending).

If you choose Activity Log, you will receive events related to all activities within your account that are supported by the Activity Log.

If you choose Email Sending, you'll also need to:

1

Choose the Sending Stream (Transactional or Bulk) for which you want to set up the webhooks.

Transactional Stream is used to send user-triggered emails to one recipient at a time, while Bulk Stream is used to send promotional emails to multiple recipients at once.

2

Choose the domain you want to receive events' data for and select one or more event types by ticking the corresponding checkbox.

3

Click the Run Test button to test the webhook setup. The code represents a dummy payload of the webhook structure and how to read it correctly. If your endpoint responds with a 200 code, you'll see a confirmation in the app. All other response codes show an error during a test.

One popular way to test webhooks outside your system is Webhook.site, but don't use it for production.

4

If the tests are successful, click the Save button. All information will be sent to your webhook endpoint.

To edit, pause, or delete an active webhook, go back to the Webhooks tab and select the webhook you want to change.

Mailtrap webhooks are delivered only on ports 443 (for HTTPS) or 80 (for HTTP). Please be sure to use these ports only.

Activity log event structure

Activity log events include the following fields:

• event — The event type

  • Example: activity_log.user.updated

• description — The event description. Meant to be a user-friendly representation of the event type.

  • Example: updated the user profile

• actor — Object representing the actor who executed the action or if the action was performed by the system actor.

  • Example: {"id":1,"type":"user","name":"Jack"} or {"name":"Mailtrap"}

• resource — Optional object representing the resource affected by the action

  • Example: {"id":17,"type":"sandbox","name":"Main"}

• changes — Optional object representing the changes made to the resource

  • Example: {"name":{"from":"John","to":"John Doe"}}

• timestamp — The timestamp in Unix epoch format

  • Example: 1735830138

All stats are built on the events, and you get most event information from the Mailtrap UI. The complete webhook structure is available in our API docs.

Retry schedule and batches

Retry schedule

If your endpoint is down and doesn't respond with 200 OK, we'll retry multiple times. The scheduling logic is as follows:

• Retry - 40 retries every 5 minutes. The webhook will be considered failed if we don't receive 200 OK with all retries. If the webhook fails, we'll pause it and notify you by email. You'll need to check its settings and resume it manually.

• Timeout - 30 seconds. If your endpoint doesn't respond within that time, the webhook event batch will go to the retry schedule.

Batches

Webhooks are sent in batches — the information we send can be grouped within one object (a JSON array).

For example, Mailtrap groups up to 500 events and sends them as a batch. The benefit is that we don't need to make 500 requests to your endpoint, and there's less load on your side. This is very beneficial for high-volume senders.

In an array of events, we collect and batch events every 30 seconds. After that time, everything that was grouped will be sent to you.