Security of a webhook

To prevent your confidential information from being intercepted and to protect your sensitive data, you can specify a https endpoint so that all data will be encrypted. However, security doesn't stop there.

Usually, endpoints are open to the world. This means that anyone with the url has access to it. To verify that a request is actually generated by SMTPeter and not a third-party that pretends to be someone else, SMTPeter signs the request headers. In this way, users can verify that requests are generated by our services.

Headers

Digest

The Digest header is added in compliance with RFC 3230. This can be used to verify message data integrity.

X-Copernica-ID

An identifier for your SMTPeter environment is added. The header will contain the data in the form of X-Copernica-ID: environment_<number>.

Signature

The headers are signed using a draft for a standard of signing HTTP messages, which you can find here.

As a keyId, an url is provided in which a key can be found in the TXT record. Currently, the field contains a full URL which can be queried for a TXT record, where a valid DKIM record can be found. To improve security, these keys are automatically rotated every month. For information on the DKIM key formatting, check out RFC 6367.

As an additional security measure, the headers in the signature should at least contain the following fields

  • (request-target) - the target resource, e.g. /path/to/your/script.php
  • Host - the hostname
  • Date - the date this request was created at
  • X-Copernica-ID - the environment identifier, see above
  • Digest - the message digest, see above

Checklist

The headers in itself are not enough to verify the message security. To make the connection fully secure, check off all steps in the following list.

  • Date is recent
  • Host header is correct
  • Digest header is correct
  • Signature header is correct
  • Signature contains at least the recommended headers
  • Signature header keyId is pointing to a copernica.com subdomain

Performing all these steps will ensure maximum security.

Example

You can find an example implementation of correct message verification here.

More information