Account Level Event Webhook

The Event Webhook provides the ability to subscribe to automatically generated HTTP POST event notifications, which can be consumed by your own applications. Notifications are generated for SMTP events and recipient engagement events. This webhook makes it easy to receive real-time notification of these events and send the data back to your own platform.

Events

A note on Asynchronous Bounces:

The way an asynchronous bounce works is that a receiving server will accept an email and will send a bounce later, sometimes days later. Because of this, in the case of an asynchronous bounce, the webhooks will show a delivered event and will then show a failure when the bounce is received.

Authentication and Access

1. Write and deploy a secure (HTTPS) endpoint that can process and respond to notifications. The URL of this endpoint is required to validate and enable this feature.
2. Either:
   1. Log into the SocketLabs platform and choose “Event Webhook” under “Configuration”, ensuring you are in the account overview and are NOT in a subaccount. Add a webhook to get the secret key. Your endpoint must respond with this secret key to validate.
   2. Generate the secret key programmatically

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.socketlabs.com/v2/event-webhook/generate-secret-key");
request.Headers.Add("Authorization", "Bearer <token>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Error Handling and Rate Limiting

Once your endpoint is configured properly, there is no hard limit to the number of notifications you can receive. If an endpoint is temporarily unavailable due to a system outage on our end, your end, or somewhere between — all notifications will be queued up for another delivery attempt in exactly the same way as email deferral works. Notification API messages will be not be permanently failed and lost unless no contact can be made for at least four days.

In the case where your endpoint becomes unresponsive for long periods of time, we may disable the notification feature on your account to prevent generating large numbers of notifications which cannot be delivered.

Endpoint Implementation

To use webhooks, users must write a handler that can process and respond to notification messages via HTTP POST. This handler must be located at a public-facing URL and must be validated by the SocketLabs platform before the URL can be activated.

To validate, the handler must support the following functionality:

•  Accepting HTTP POST messages
• Recognize the Secret Key field to confirm that SocketLabs is the sender of the HTTP POST message
• Respond to official notification messages with `200 OK` HTTP Response.

Endpoint Implementation

HTTPS communication is required on your endpoint. Using unencrypted HTTP can pose a number of security risks. By the nature of the data being transmitted, Event Webhook related calls made to your endpoint contain your SocketLabs subaccount ID and Secret Key, as well as PII (Personally Identifiable Information) belonging to end-users, such as email address and IP address. Insecure transfer of such data over HTTP may pose data security risks.

Implementation Notes

If the Secret Key does not match in a notification message, your application should return a 401 error response.

All new endpoints will be in the JSON (`application/json` ) data format.

Endpoint Validation

Once a handler application is installed and configured at a URL, this URL should be entered into the ‘Endpoint URL’ field in the SocketLabs platform before using the Validate button.

Validation Failures

Likely reasons for this validation to fail include:

• The endpoint is unreachable by SocketLabs, perhaps due to being behind a firewall.
• The handler is not accepting HTTP POST messages.
• The handler is not responding to notification messages with a `200` HTTP response.

Validation Failures

We recommend checking network security settings as well as examining the POST and POST Response data in the handler if the Endpoint URL validation initially fails.

When testing your handler, you can use the configuration page in the SocketLabs platform to send test notifications.

If your endpoint resides behind a firewall, you may need to allow SocketLabs’ infrastructure to access your network to receive notifications at your endpoint. Event Webhooks can send notifications from multiple pieces of our infrastructure. It is therefore recommended that you allow our entire outbound IP range, 142.0.176.0/20.

Endpoint Testing

Once you have deployed and validated your endpoint, you can use the “Event Tester” feature in the SocketLabs platform to send sample notifications to your endpoint for testing. Select the type of sample notification to generate from the dropdown, then click the “Test” button. This will generate and send a notification to your endpoint. We will also generate a preview of what the body of the notification will look like in your preferred data format.

Once you send a test notification, an indicator will pop up showing the HTTP response code that we received from your endpoint as well as whether the notification was accepted.

Endpoint

https://api.socketlabs.com/v2/event-webhook/:webhookID

Example Request: Sent Messages

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.socketlabs.com/v2/event-webhook/:webhookId/perform-test?type=sent");
request.Headers.Add("Authorization", "Bearer <token>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Example Response: Sent Messages

{
  "data": {
    "Type": "Delivered",
    "Response": "Sample Response",
    "LocalIP": ":01",
    "RemoteMta": "Sample RemoteMta",
    "DateTime": "2022-09-07T17:49:08.8139901Z",
    "MailingId": "SLNL-0-9999999-9999999",
    "MessageId": "SampleMessageId",
    "Address": "email@example.com",
    "ServerId": 16332,
    "SecretKey": "n7BJk25EtAr39Sfa4K8R",
    "Data": {
      "Meta": [
        {
          "x-mycustommetadata": "I am custom metadata"
        }
      ],
      "Tags": [
        "Same Tag",
        "Same Message"
      ]
    }
  }
}

For more code examples and to dig into our subaccount level event webhook, see our Event Webhook documentation.

Other Resources

• Authentication 
• Creating IP Pools 
• Creating Subaccounts 
• Subaccount Custom Bounce Domain Authentication 
• Subaccount DKIM Authentication 
• Subaccount Engagement Tracking 
• Injection API 
• SMTP 
• Account Level Event Webhook