Webhook best practices

When creating webhooks, consider these best practices to keep them efficient and secure.

Retry Logic

There are a few scenarios where we retry webhooks. Each scenario involves interpreting the HTTP status code received when making an attempt to the configured webhook URL.

  • We ignore and don't retry for any 30X and 4XX status codes (except 429, which we do retry).
  • We retry on any 429 or 5XX status code.

We retry each of the aforementioned scenarios three times (unless one of those tries was successful). We also use an exponential backoff process for each of the retries. These errors and retires are logged in the form of sync failures.


Authentication Logic

If the authentication type is OAuth2 and 401, 403, or 419 errors happen, we'll automatically re-auth and retry.

We retry three times (unless one of those tries was successful). We also use an exponential backoff process for each of the retries. These errors and retires are logged in the form of sync failures.


Event Handling

Webhooks out of Simon follow the basic premises around making an HTTP request. As a result, here are some known limitations based on web standards (out of our control):

  • The body of a POST request can't exceed 2MB. The POST of a request can't exceed 2,097,152 bytes (or characters, although that's not exact). That includes all the stuff you don't usually see like white-space, encoding characters, etc. Endpoints are encoded.
  • GET requests don't use body to pass data. It appends all the pieces of data to the end of a URL. Unfortunately, URLs are much more strict. The maximum number of characters for a URL is 2,048
  • At a minimum, we recommend using and configuring urls that are under the HTTPS protocol
  • Including authorization in your requests is also a good way to combat security issues, however the endpoint you're connecting to needs to support this. You need to conform to the endpoint's specifications or you can receive errors.

Order of Events

Event processing happens as-is. However, what happens is fully configured in individual segments and flows. Events are just a starting point to begin processing.


Batch Request Type

When batching, the payload itself is contacts batched in groups of Batch size specified, each contact consisting of a JSON object of the key-value pairs defined as the payload.


Nested JSON Objects

Dot notation may be used to construct nested JSON objects as payloads - for instance, a payload key/value pair of outer_object.inner_object.value : True becomes { outer_object: { inner_object: {value: True } } }. This only applies for JSON-encoded parameters, not form-encoded POST requests.