Webhooks

Webhooks are API endpoints that you create to receive messages from Optoro when events occur. This page outlines how to design webhooks that can properly receive data from Optoro.

Configuration

Optoro's Client Success team will work with you to configure webhooks. Required information includes:

A list of webhooks to enable
A URL for each webhook
Authentication details

See API specifications for details on the messages that will be sent to webhooks.

Webhooks vs. Customer Endpoints

There are two flavors of HTTP endpoints provided by you, the customer: webhooks and customer endpoints. This section aims to differentiate the two.

Webhooks are called when events occur in Optoro's system, while customer endpoints are called when Optoro's system needs information. Think of this as telling vs. asking.
Webhook responses only need to acknowledge that the request was received, while customer endpoints need to respond with additional data.
Webhook responses are not acted upon (other than the retry behavior detailed below), while customer endpoint responses influence the actions of Optoro's system.

The rest of this page only pertains to webhooks. See the API specifications for more details on various customer endpoints.

Design Considerations

When creating a webhook endpoint there are some design considerations to be aware of.

Message Behaviors

Optoro's system strives for at-least-once delivery of messages to your webhook. This tradeoff prioritizes reliable message delivery and ease of integration at the cost of some duplicate content. While Optoro will attempt to keep duplicate messages to a minimum, your webhook must be able to handle them.

Optoro's system also parallelizes message delivery. This means that messages are not guaranteed to be sent in chronological order. Most messages will include a timestamp for this reason.

Authentication

Webhooks must be authenticated. The following authentication mechanisms are supported:

Basic Auth
OAuth 2
AWS SigV4
API key in an HTTP header

Credentials and other secrets should be sent to Optoro's Client Success team as encrypted files. Secrets will remain encrypted in Optoro's system.

Content Type

All messages are formatted as JSON, so webhooks must support JSON content. Messages will include the content type in the HTTP request headers.

Copy

Copied

Content-Type: application/json
Accept: application/json

HTTP Verbs

All messages use the POST HTTP verb, so webhooks must support POST requests.

HTTP Responses

Optoro's system checks if a message is processed successfully based on the HTTP response status code received from your webhook. We recommend responding with the following set of response codes.

2xx series response codes

Indicates that your webhook successfully received, understood, and accepted the message. All 2xx response codes are treated the same. We recommend responding with a 200 OK status code.

4xx series response codes

Indicates that Optoro's system must take action before trying the request again. The only 4xx status code that can be resolved automatically is a 401. Optoro's system will authenticate again before retrying the request.

Webhooks should not respond with a 400, 422, or any other status code that indicates a validation error. If a message is not valid or relevant to your webhook, quietly ignore the message and respond with a 200 OK status code. Responding to messages with a validation error will cause unnecessary noise in Optoro's monitoring system.

5xx series response codes

Indicates that your webhook failed, and the message should be retried. The following status codes will be retried. Timeout errors will also be retried.

500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

Optoro's system will retry failed messages with an exponential backoff for up to 32 hours. In the event of a webhook outage, all messages will eventually be delivered given the issue is resolved within a day. Contact Optoro's Client Success team to retry messages outside of this window. Messages are retained for 30 days.

TLS and SSL Certificate Security Specifications

Optoro only supports communication with webhooks via HTTPs using TLS 1.2. All SSL certificates installed on your servers MUST be signed by a Globally Trusted Certificate Authority. Install intermediate certificates on your machines in addition to the signed certificate for your domain. This is security best practice. Optoro will not install intermediate certificates on our servers.