<commit_before>---
layout: page
weight: 10
title: Event Webhook
navigation:
  show: true
---

{% info %}
Available to all accounts except [Legacy Lite]({{root_url}}/Classroom/Basics/Billing/legacy_lite_plan.html).
{% endinfo %}

SendGrid's Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. Common uses of this data are to remove unsubscribes, react to spam reports, [determine unengaged recipients]({{site.blog_url}}/infer-engagement-with-the-event-api/), identify bounced email addresses, or create advanced analytics of your email program. With Unique Arguments and Category parameters, you can insert dynamic data that will help build a sharp, clear image of your mailings.

{% info %}
If you'd like to see how one of our customers uses the Event Webhook, check out [Leveraging SendGrid's Event Webhook]({{site.blog_url}}/leveraging-sendgrids-event-api/).
{% endinfo %}

{% info %}
There are a number of pre-made integrations for the SendGrid Event Webhook that make processing events easy. You can find them in the [Library Index]({{root_url}}/Integrate/libraries.html#-Webhook-Libraries).
{% endinfo %}

{% anchor h2 %}
Setup
{% endanchor %}

To setup the Event Webhook via our web interface, login and go to the [mail settings page]({{site.app_url}}/settings/mail_settings) and click on the Event Notification setting, then click on the "edit" link. Check the boxes next to the type of events that you want posted to your web server, then enter in the URL you have setup to receive POSTs from our servers when an event occurs.

The Event Webhook may also be setup by using our [Filter Settings Endpoint]({{root_url}}/API_Reference/Web_API/filter_settings.html#-Event-Notification).

{% info %}
We support basic HTTP authentication in our Event Webhook. Those who wish to implement can provide credentials in the post event url field on the app settings page. Below is an example of the post url with authentication included.
{% endinfo %}

{% codeblock lang:html %}
http(s)://username:password@domain/foo.php
{% endcodeblock %}


{% warning %}
If you wish to receive encrypted posts, we require that your callback URL support TLS 1.2.
{% endwarning %}

{% anchor h2 %}
Requests
{% endanchor %}

You will receive an **HTTP POST** containing a JSON array of multiple events in one request after a very short delay. These POSTs will be sent to the URL you have defined in the Event Notification app options.

{% info %}
Events currently post every 1 second or when the batch size reaches 1MB (one megabyte), whichever occurs first. This is per server, so the webhook URL may receive tens of posts per second.
{% endinfo %}

{% anchor h3 %}
Event POST Example
{% endanchor %}

{% codeblock lang:json %}
[
  {
    "sg_message_id":"sendgrid_internal_message_id",
    "email": "<EMAIL>",
    "timestamp": 1337197600,
    "smtp-id": "<4FB4041F.608050<EMAIL>>",
    "event": "processed"
  },
  {
    "sg_message_id":"sendgrid_internal_message_id",
    "email": "<EMAIL>",<commit_msg>Update event.md<commit_after>---
layout: page
weight: 10
title: Event Webhook
navigation:
  show: true
---

{% info %}
Available to all accounts except [Legacy Lite]({{root_url}}/Classroom/Basics/Billing/legacy_lite_plan.html).
{% endinfo %}

SendGrid's Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. Common uses of this data are to remove unsubscribes, react to spam reports, [determine unengaged recipients]({{site.blog_url}}/infer-engagement-with-the-event-api/), identify bounced email addresses, or create advanced analytics of your email program. With Unique Arguments and Category parameters, you can insert dynamic data that will help build a sharp, clear image of your mailings.

{% info %}
If you'd like to see how one of our customers uses the Event Webhook, check out [Leveraging SendGrid's Event Webhook]({{site.blog_url}}/leveraging-sendgrids-event-api/).
{% endinfo %}

{% info %}
There are a number of pre-made integrations for the SendGrid Event Webhook that make processing events easy. You can find them in the [Library Index]({{root_url}}/Integrate/libraries.html#-Webhook-Libraries).
{% endinfo %}

{% anchor h2 %}
Setup
{% endanchor %}

To setup the Event Webhook via our web interface, login and go to the [mail settings page]({{site.app_url}}/settings/mail_settings) and click on the Event Notification setting, then click on the "edit" link. Check the boxes next to the type of events that you want posted to your web server, then enter in the URL you have setup to receive POSTs from our servers when an event occurs.

The Event Webhook may also be setup by using our [Filter Settings Endpoint]({{root_url}}/API_Reference/Web_API/filter_settings.html#-Event-Notification).

{% info %}
We support basic HTTP authentication in our Event Webhook. Those who wish to implement can provide credentials in the post event url field on the app settings page. Below is an example of the post url with authentication included.
{% endinfo %}

{% codeblock lang:html %}
http(s)://username:password@domain/foo.php
{% endcodeblock %}


{% warning %}
If you wish to receive encrypted posts, we require that your callback URL support TLS 1.2.
{% endwarning %}

{% anchor h2 %}
Requests
{% endanchor %}

You will receive an **HTTP POST** containing a JSON array of multiple events in one request after a very short delay. These POSTs will be sent to the URL you have defined in the Event Notification app options.

{% info %}
Events currently post every 30 second or when the batch size reaches 768K (seven hundred sixty-eight kilobytes), whichever occurs first. This is per server, so the webhook URL may receive tens of posts per second.
{% endinfo %}

{% anchor h3 %}
Event POST Example
{% endanchor %}

{% codeblock lang:json %}
[
  {
    "sg_message_id":"sendgrid_internal_message_id",
    "email": "<EMAIL>",
    "timestamp": 1337197600,
    "smtp-id": "<<EMAIL>>",
    "event": "processed"
  },
  {
    "sg_message_id":"sendgrid_internal_message_id",
    "email": "<EMAIL>",
{'fraction_non_alphanumeric': 0.09456380208333333, 'fraction_numerical': 0.008463541666666666, 'mean_word_length': 4.581289736603088, 'pattern_counts': {'":': 14, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7376575', 'n_tokens_mistral': 1841, 'n_tokens_neox': 1656, 'n_words': 772}