Event Webhooks: Authentication and Access

Event Webhooks are configured and validated individually for each server for SocketLabs Simple Sender (v1) or at the subaccount and/or account level for SocketLabs Complex Sender (v2).

To receive Webhook events, users must write a handler that can process and respond to notification messages via HTTP POST. In order to validate, this handler must:

• Be located at a public-facing URL
• Have an HTTPS prefix, as a valid SSL certificate is required
• Be able to process and store notifications as they arrive
• Respond to official notification messages with a 200 OK HTTP response

All notifications sent from our platform will contain the Secret Key as well as your ServerID, which should be used to ensure that all notifications are coming from our systems. 

We also ask that if the Secret Key does not match in a notification message, your application should return a 401 error response. 

All endpoints created after June of 2021 use JSON (application/json ) data format. UrlEncoded (application/x-www-form-urlencoded) was previously supported and is now considered legacy and will be deprecated in the future. 

Once a handler application is installed and configured at a URL with the above requirements, this web address should be entered into the 'Endpoint URL'.

SocketLabs Simple Sender (v1)

For SocketLabs Simple Sender (v1) this will be in your SocketLabs server under Configuration -> Event Webhooks. Then, click Validate.

SocketLabs Complex Sender (v2)

For SocketLabs Complex (V2) the event webhooks are configured at either or both the Account level, and individually for each subaccount. An account or subaccount can have multiple distinct webhooks. Account level webhooks will receive events for all subaccounts. Subaccount level webhooks allow for just events from a specific subaccount to be received.  

For an account level event webhook for a complex sender, the endpoint will be added from the main account page, under Configuration -> Event Webhooks. Then click Validate.  

For an subaccount level event webhook for a complex sender, the endpoint will be added from the subaccount, under Configuration -> Event Webhooks. Then click Validate.  

Validation Failure

Likely reasons for this validation process to fail include: 

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

We therefore 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. 

Getting The Most From Event Webhooks

Additional Values

When handling delivery notification email messages, your applications should be able to handle additional, undocumented values in the PostBody as we may add additional attributes in future versions of this webhook.

We also highly recommend storing all notification data received via the webhook in a local database so that your local applications can query and access this data as needed in an efficient and timely manner.

Since most of the data for these notifications is populated based on responses from receiving mail servers, the values can vary widely in size. If you will be storing these responses in a database, it is recommended that you store the data in a format that can handle larger string values. 

We do not currently support batching of events. Each event generated will result in a HTTP POST to your endpoint.

Multiple Notifications

Some messages may result in multiple notifications being generated, including a Delivery and a Failure notification. This can be for a variety of reasons such as an asynchronous bounce, an out-of-office reply, or an automatic forward setup on the recipient's end. In these cases, we recommend examining the failure notification to determine if it was a "true" failure or one of these other scenarios. 

Security

Some of the values contained in the PostBody may include data obtained from third-party mail servers and web browsers. SocketLabs will provide this data AS IS in the PostBody, therefore it is important to treat this data as untrusted. If you are storing data from the PostBody in your database, it is important to use prepared statements and/or parameterized queries to prevent potential injection attacks. Similarly, if you will be displaying this data to end users, it is important to make sure the data is encoded and/or escaped to avoid potential cross-site scripting or code execution. 

Only HTTPS communication is allowed for your events. Using unencrypted HTTP can pose several security risks. By the nature of the data being transmitted, event webhook-related calls made to your endpoint contain your SocketLabs server 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 (i.e.: confidentiality and integrity). 

Once you have deployed and validated your endpoint, you can use the "Event Tester" feature 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. 

Firewalls

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

Error Handling and Rate Limiting

Once your endpoint is configured properly, there is no hard limit to the number of events you can receive. If an endpoint is temporarily unavailable due to a system outage on our end, your end, or somewhere between — all events will be queued up for another delivery attempt in the same way an email deferral works. Webhook events will 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 extended periods of time, we may disable the Event Webhook feature on your server to prevent generating large numbers of events which cannot be delivered. We would notify a user via email if this occurred, and the feature would need to be reconfigured via the portal to be reactivated. 

For event examples, see Event Webhooks: Events