Callbacks are a way for a third-party system to receive informative calls from the Vibes Platform when specified data has changed. The callback itself is a Vibes-initiated HTTP request that is sent to the third-party system to notify them of activity in the Vibes system.
The third-party system, also known as your endpoint, is responsible for storing and recording this information, along with returning an appropriate HTTP response. This article will outline the technical specifications required of any endpoint receiving Vibes-initiated callbacks.
Multiple Destination URLs
You can have a same callback go to multiple destination URLs by registering callbacks with different destination URLs. You can register up to 50 endpoints.
Skip to learning about specific callbacks:
- Acquisition Campaign Callback Types
- Event-Triggered Callback Types
- Person Callback Types
- Push Device Callback Types
- Subscription Callback Types
- Subscription List Callback Types
- Unmatched Message Callback Types
- Wallet Callback Types
Endpoint Specifications
Avoid performance disruptions
To ensure adequate performance and avoid rate limiting or other errors, you should keep the callback code as small as possible. To avoid connection timeouts or rate limiting from the Vibes system, any extensive back-end calls or updates should be done asynchronously rather than keeping the callback HTTP call open.
Registration limitations
One callback can be registered per callback type, per company account. Person callbacks, because they are related to the entire mobile database, and not to any one company, can only have one registration callback per mobile database.
As part of the configuration, customers can be notified of failed deliveries by setting up an automated email notification process for when a callback fails to notify.
Originating IP address ranges
The following Vibes IP address ranges are available if a customer wants to list them as allowed traffic:
US
- 35.155.139.143
- 52.32.61.199
- 35.161.244.84
- 18.205.120.48
- 52.22.43.57
- 18.232.9.131
EU
- 34.243.232.57
- 52.48.241.82
- 34.249.188.130
- 54.247.36.51
- 34.253.250.65
- 54.217.181.160
HTTP responses
It is the receiver's responsibility to ensure processing and to return the appropriate error codes. Depending on the error code, Vibes will attempt to redeliver the events up to the maximum number of tries. It is important that the callback endpoint not return errors when no retry attempts are desired. In that case, simply accepting the message with a 2XX response is sufficient.
It is possible, in rare circumstances, that an event is delivered more than once in error scenarios, or when an improper HTTP Response code was returned or timed out. All customer endpoints must be able to handle this case without causing conflicts within their system and return a response in the 2XX range.
Below is a chart of the HTTP response codes that your endpoint should return, depending on the situation.
| HTTP Response Code | Description |
|---|---|
| 2XX | OK - Message was accepted and processed successfully. |
| 4XX | Permanent event specific error conditions that should not be retried. It will immediately put the event in a failure queue and notify the customer for resolution. |
| 3XX OR 5XX | Temporary error conditions that indicate a transient failure. These events will be retried based on the configured retry scheme, and then, if still failing, it will put the event in a failure queue and notify the customer for resolution. These can also trigger downed states within a URL that may suspend additional delivery attempts for short periods of time to avoid saturating a down (or slow) service. |
Callback Structure
All callbacks have a similar base structure to indicate the type of callback as well as specific information about each event. All the general callback information will be in the HTTP Headers for reference, parsing, and routing. The HTTP body will contain the specific data that is relevant to the callback event.
HTTP headers
| HTTP Response Code | Description |
|---|---|
| X-Event-Id | Unique Event ID for the event. |
| X-Company-Id | The Company ID that the request is for. |
| X-Callback-Id | The Callback ID that generated this callback event. |
| X-Delivery-Attempts | The number of delivery attempts. |
| X-Event-Type | The free text type of the event. |
HTTP body
{
<callback specific data>
}