RELEX Data API for Example Customer (v4.28.3)

This documentation describes the data resources and technical details available for the RELEX Data API.

In short:

• The data resources are divided by tags according to data type.
• The payload contents of individual resources are described in detail with example payload data.

⚠️ All API requests must be made over HTTPS

Calls made over plain HTTP fail and return HTTP Status Code 400 Bad Request.

• A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. In practice, the resource most often maps to a corresponding database table, but not always.
• An environment (also tier) is a computer system or set of systems in which a computer program or software component is deployed and executed. The most common setup for RELEX Data API clients is to have user-acceptance-test and production environments.

REST stands for Representational State Transfer which is an architectural pattern describing how distributed systems can expose a consistent interface through the web. When people use the term REST API, they are generally referring to an API accessed via HTTP protocol at a predefined set of URLs.

The RELEX Data API is built around these concepts and has predictable resource-oriented URLs, accepts JSON-encoded requests, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and HTTP verbs.

The biggest difference to traditional record-oriented REST APIs is that the RELEX Data API can ingest multiple records into a single HTTP request. This allows the clients to bundle individual changes into small batches and send them in one request.

This typically increases performance and reduces the overhead of handling individual requests. This style is prevalent in the RELEX Data API regardless of the HTTP verb used.

⚠️ We strongly recommend using micro-batches (small batches of records) whenever possible.

Micro-batches provide significantly better throughput, reduce request overhead, and help avoid hitting rate limits during high-volume updates.

The API is documented in OpenAPI format and is based on the Data API provided by RELEX. For more information on OpenAPI format, refer to the OpenAPI Specification. This documentation is created by using the ReDoc tool.

The RELEX Data API is designed to receive data as a continuous stream. The API allows the clients to send the data whenever changes happen, either one record at a time or in batches of records. Hence, there are no explicit start and end notions for a set of data.

Instead, data is processed as it arrives, whenever the backend systems deem it appropriate. While typically the data is processed in the order it arrives, due to the nature of distributed systems, RELEX may process data received in subsequent requests in a different order than originally sent.

⚠️ Avoid making immediate subsequent updates to the same record

We discourage making numerous mutative API calls to the same records in rapid succession, in other words, POST and DELETE requests.

Instead, we recommend batching the same records into one request. Making quick consecutive updates for the same record may cause a race condition that can cause the data to get out of sync between the client and RELEX.

⚠️ Using micro-batches is the preferred pattern for continuous data streams.

Sending multiple small updates in one batch reduces the number of API calls, minimizes the chance of race conditions, and significantly lowers the likelihood of hitting rate limits during heavy traffic.
Single-record requests should be reserved for low-volume or exceptional cases only.

Cross-endpoint record coordination

The RELEX Data API does not coordinate supplied records across endpoints. This means that if two records are supplied to two distinct endpoints, the API might make them available for target applications to consume in either order (records within one endpoint will always be made available in the order they were supplied to the API). If the two records are somehow related to each other and no additional steps were taken, the end result could depend on which record is consumed first. To prevent this, target applications might take additional steps to guarantee identical results regardless of inter-topic consumption order. Using UPSERT logic (i.e. update if exists, otherwise create) is a common way to accomplish this.

Many endpoints are connected to each other in the data models of target applications. For example, the Product Locations endpoint expects both a product code and a location code. The given codes are typically used to link the supplied record to the corresponding product and location in the target application. Such links are only possible if the referenced records exist. To remove the dependency on consumption order, an incoming product-location record might result in automatic creation of the referenced product and location if they do not already exist so that the needed references are in place. The same principle applies to many other endpoints. When automatic reference creation creates an entry, typically only the required fields and fields with default values are populated.

The RELEX Data API uses JSON as the format for data serialization. The JSON payload of the API has a root-level object that contains a meta-object and data array element. Requests need to define a Content-Type header and be set to application/json.

All resources have a defined schema, and the details of each resource can be examined in the resource specifications in this document.

Dates, times and timestamps in RELEX Data API generlly follows the Date and Times JSON Schema format which is based on RFC 3339 standard, unless otherwise specified (for example endpoints with time fields are usually accepting only hh:mm).

If the consumer application supports localization of names, the corresponding name for a specific language can be set by adding one of the following fields to the schema.

All inbound API resources work in the same way: they consist of synchronous and asynchronous parts.

• Authentication, data validation, and persisting incoming data are done synchronously and immediately when the client sends the data.
• The client receives a response with a 200 HTTP status code if RELEX is able to accept the request successfully and process it further.
• If any part of the synchronous part fails, a non-2xx status code is returned. A failure indicates that RELEX has not received the data successfully, and it can not be processed further. Consequently, the client must send the data again.
• After the synchronous operation, the data processing moves to an asynchronous stage. All subsequent actions are done asynchronously in the RELEX Platform outside the request-reply context.

The Data API also includes a feature called Error API that the client can use to check for errors. For more information, see the asynchronous section.

The RELEX Data API does not support payload compression. Requests must omit the Content-Encoding header or define it as none.

The RELEX Data API uses all-or-nothing semantics. For a given payload, either all records are accepted or none are. In other words, one invalid record in an otherwise valid set makes the whole set invalid.

The invalid record must be fixed or removed, and the payload sent again to allow the valid records to be processed.

On the other hand, the downstream applications handle records individually. This means that once the Data API has accepted the records, the later parts of the processing behave differently with invalid records.

Problematic records are put aside and logged (see Event API), and processing continues from the next record.

The RELEX Data API supports bespoke data models. To facilitate receiving custom data via standard API, the API provides bespoke resources for custom fields and resources.

The customer-specific API document includes all the resources in full, containing both standard and custom fields and resources, and their schemas.

Custom resources

Custom resources follow the same concepts and patterns as standard resources, including the following patterns:

• HTTP verbs: verb to denote the action type
• Naming: human-readable resource names, plural, lowercase, separated by an underscore
• Return codes: 2xx for success, 4xx and 5xx for failures

Custom resources are added to a dedicated namespace. This is done to prevent a naming collision when new resources are added to the standard RELEX Data API interface. The namespace for custom resources is custom. This makes the resource path look like/data/custom/resource.

Custom fields

Similarly to custom resources, customer-specific fields can also be added to standard REST interfaces.

Custom fields follow the same concepts as standard fields:

• Naming: human-readable field names, plural, lowercase, separated by an underscore

As with resources, custom fields are also namespaced. The namespacing is done by prefixing each custom field name. The prefix is custom_. The resource remains otherwise the same, and all existing resources are not affected.

As an example, when a color field is added to the products resource, the corresponding attribute in the JSON payload is named custom_colour and is available at the /data/master/products resource.

You can also remove optional fields from the standard resources, but there is rarely a need for that because they can be freely omitted from the request payload.

It is not possible to add arbitrary fields to the resources. Each field, standard and custom, must be declared in the resource schema.

ℹ️ Custom resources do not use field prefixes

The fields in custom resources do not need to have the prefix since they are already under a distinct namespace. Thus, the fields in custom resources have no special naming requirements.

To support the managed evolution of the Data API, we version its public interfaces. We have one version number that communicates all the changes to the API. This is simply called the API version.

Under the hood, the API version is a combination of the following:

• Core version comprising of API semantics and usage patterns, such as authorization, payload formats, and details of requests and responses. This versioning is referred to as the Core version in this document.
• Data model version comprising of the standard interfaces, payload schemas, and customization to existing or new resources requested by the customer. This versioning is referred to as the data model version in this document.

The API version is an abstraction over the two separate version concepts. For an API client, it is enough just to follow the API version.

Semantic versioning

All our version identifiers follow semantic versioning principles. Each change to the semantics of the API increments one of the three parts of the API version number: MAJOR, MINOR, or PATCH.

The following changes guarantee an increment in the API version number:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backward-compatible manner, and
• PATCH version when you make backward-compatible bug fixes.

Additional labels for pre-release and build metadata can be used as extensions to the MAJOR.MINOR.PATCH format. For instance, 4.2.2-beta is an allowed version specifier.

The versioning policy guarantees that only a MAJOR version upgrade can require the client to make changes.

One environment can host only one version at a time: it is not possible to have more than one version of the API running simultaneously in, for example, a production environment.

However, different environments may run different versions concurrently. For example, a user-acceptance-test version can have a more recent version running than the production API.

Version compatibility and deprecation

RELEX strives to the utmost to maintain API compatibility between versions by introducing changes in a non-breaking manner whenever possible.

When the API evolves, new features are typically added as additional resources, new fields, or new features. We avoid removing or changing existing functionality in a breaking way unless there is a very compelling reason, such as a security improvement.

With this approach, the API remains compatible even in the case of new or improved features, and the API clients can mostly remain the same. The clients may simply ignore the elements that are introduced without any adverse consequences. Only when a client explicitly takes a new feature into use, must it be adapted.

In the rare event of a breaking change, a new MAJOR core version is introduced. In that case, the feature is put behind a feature flag. The flag by default is set to follow the existing behavior.

The customer has three (3) months to adapt to the upcoming version change before the feature flag is automatically made to follow the new behavior. Upgrade instructions are provided.

There are two exceptions to this rule: A critical security-related issue is fixed immediately. If we discover a critical security issue in the API, we do whatever is necessary to mitigate the issue as soon as possible. The fix may include disabling the vulnerable functionality until a proper solution is available. In that case, the clients need to adapt to the changes quickly. Changes to customer data models are visible immediately and are not behind feature flags.

Core versioning

The core version is derived from the changes in the system behavior, features, or other non-customer-specific changes.

Changes to the core version can be; for example:

• Introducing a new metadata resource to the API,
• Changing the authentication pattern, or
• Adding a new common field to a response payload.

The core version is not affected by changes to the data model or internal changes that do not affect the functional behavior of the system, such as updates to internal dependencies or performance improvements.

Data model versioning

Data API supports customer-specific bespoke fields and resources, and, commonly, customers use this powerful feature to tailor the API to their needs.

During the project phase, it is customary that the APIs evolve rapidly. The changes may be small but breaking; for instance, changing a field data type. Or the change can be big but non-breaking, such as adding two new resources to the data model. Because the pace and nature of these changes are unrelated to API behavioral changes, the data model and the core version are versioned separately.

API version number

The exact version for the API combines both the core version and the data model version. It is formed by summing each semantic version number. For instance, core version 1.2.3 and data model version 4.3.2 creates an API version 5.5.5. Possible suffixes are concatenated. All version numbers can be queried through the API using a corresponding resource.

Under REST principles, a URL identifies a resource. The following URL design patterns are considered REST best practices, which the RELEX Data API also follows.

• URLs should include nouns, not verbs
• Use plural nouns for consistency (no singular nouns)
• Use HTTP methods (HTTP/1.1) to operate on the resources

For consistency, we have also defined the following practices for resource URIs:

• written in lower-case letters
• spaces are replaced with dashes (-)
• resources must reside in pre-defined namespaces

The URL for the API is PROTOCOL://ENV-GEOGRAPHY.rest.HOST/CUSTOMER, which consists of the following parts:

• PROTOCOL always HTTPS
• ENV denoting the environment, for example, prod
• GEOGRAPHY denoting the geography or region, for example, us
• HOST denoting the hostname for the service, always relexsolutions.com
• CUSTOMER denoting the name of the customer, for example, bigretailer

The API base URL, therefore, could be; for example:

• uat: uat-eu.rest.relexsolutions.com
• prod: eu.rest.relexsolutions.com

Resource namespaces

The RELEX Data API exposes the following top-level resource namespaces:

• meta: metadata resources for business data-related aspects, such as version information
• data: data namespace for business data
  • master: master data resources
  • custom: custom customer-specific resources
  • transactions: transaction data resources

Data operations and HTTP verbs

This section describes how data operations (List, Upsert, and Delete) are mapped to HTTP verbs.

The RELEX Data API deviates slightly from the traditional REST approach by commonly treating the data as collections of records instead of singular records. In practice, the API accepts and returns multiple records in one request. The other notable deviation is the usage of POST for both creating new records and updating existing records.

As RELEX operates with big datasets, the number of records sent and received through the API can be fairly large. Encoding multiple records in one request increases the API throughput as it dramatically reduces the number of individual requests that clients need to make.

This pattern applies to most of the resources regardless of the used verb. A client may create several records in a single request using the POST verb, or delete one or more records using the DELETE verb.

An important concept closely related to HTTP verbs is idempotency. An idempotent method means that the result of a successfully performed request is independent of the number of times the request is executed. Non-idempotent is the opposite: It means that the result may change if the request is performed more than once, even if the data remains the same.

HTTP POST for data resources

HTTP POST is used for sending records to the API in a maximum of one (1) megabyte-sized chunks per single request. A single POST request may contain one or more records that are ingested into RELEX systems.

Data API POST interfaces are based on the colloquial upsert model: new records are created for the payload items that have no matching counterparts in the RELEX database. Records that have matching database records are updated. A single request may simultaneously create new records and update existing records.

POST requests to data resources are idempotent. Resending the same payload is safe and produces the same result. In practice, this means that if you are uncertain whether a request was received, for example due to a network failure before the response arrived, you can resend the same request without risk of creating duplicate records.

Suggestion for data processing

When sending data using RELEX Data API we recommend that the customer provide a batch_id along with each request. It is useful for the customer and RELEX to correlate processing output artifacts such as logs to the request payload.

Together within the batch_id we recommend sending a timestamp within each request. This is used internally for logging, and telemetry purposes.

These attributes are submitted in the request body meta section. Both items are optional but highly recommended to guarantee efficient operation.

• A batch_id is a customer-specified identifier for the logical batch that is being sent. The format is UUID. Each logically separate request must have a different batch_id. Retries of the same request must use the same batch_id.
• A timestamp is a value RELEX uses internally. The format of the value must be a monotonically increasing integer. If the data is sent from multiple different sources to a single resource, the clients must ensure that the different systems use the same source for the timestamp value.

HTTP DELETE for data resources

HTTP DELETE is used for deleting records in RELEX. A DELETE request may delete one or more records at a time.

DELETE request is idempotent. This practice means that the first request deletes the specified rows, and subsequent retries are ignored.

Deleting records is possible from master data tables. The full list of resources supporting the DELETE method can be seen in the resources section of this document.

HTTP GET for data resources

HTTP GET is used for fetching records from RELEX. A GET response contains zero or more records stored in RELEX databases.

GET request is idempotent and causes no side effects.

The RELEX Data API imposes limits on incoming web requests to ensure performance, reliability, and efficiency. The API sets the following limits:

• The maximum size of any POST request is 1 MB
• The rate limit of requests per second is 5 (subject to discussion)

In case the limits are exceeded, a corresponding HTTP status code is returned with an error message detailing the issue.

⚠️ Exceeding payload sizes

In the event that the payload size exceeds 1 MB, the data needs to be split into smaller chunks and sent in multiple independent requests. Each chunk is then processed separately by RELEX.

ℹ️ API limits are subject to change and appropriate values are determined during the implementation project.

The RELEX Data API imposes no limits on return payloads. The payload size can be arbitrarily large.

Exceeding limits

In the event of exceeding the rate-limit and receiving an HTTP status code 429, the error payload is the following:

    {
    "type": "https://example.com/probs/rate-limit-exceeded",
    "title": "You have exceeded rate limit",
    "status": 429,
    "detail": "Your rate limit has been exceeded. Please retry later."
    }

In the event of exceeding the request payload size-limit and receiving an HTTP status code 413, the error payload is the following:

    {
    "type": "https://example.com/probs/size-limit-exceeded",
    "title": "Payload Too Large",
    "status": 413,
    "detail": "Payload was larger than 1mb"
    }

The RELEX Data API uses regular HTTP response codes to indicate the various failures an API request can return. Codes in the 4xx range indicate an error on the client side, for example, the resource name was incorrect. Codes in the 5xx range indicate an error within RELEX services.

To convey details about errors to clients in JSON responses, the RELEX Data API uses the RFC 7807 standard.

The RELEX Data API provides a resource that can be used to query errors emitted during the asynchronous processing; that is, after the data has been successfully ingested by the RELEX Data API.

The nature of asynchronous processing is such that errors can appear at any moment until the data processing finishes. For this reason, the response to the request might be different over time. Hence, the resource needs to be queried periodically to get the full result.

Fetching errors

There are two mutually exclusive ways of fetching errors: either by request or by time.

For fetching errors for a particular request, the client must supply a request_id. The request_id parameter is an identifier that is returned in the response for all POST and DELETE requests. The identifier can then be used later to track the ingestion errors for that particular request. Think of it as a handle for an asynchronous background processing job.

For fetching errors by time, a start_timestamp (inclusive) and end_timestamp (exclusive) pair must be supplied. Timestamps can be used for fetching all ingestion errors that occurred during the specified time window.

Fetching by request and timestamp are mutually exclusive. They cannot be used simultaneously.

Pagination of error responses

To limit the potential response size, the number of errors returned in one response is capped.

The following optional query parameters must be used when the number of errors exceeds the amount one response can return.

• page is used to define the desired set of all available sets when the amount of errors in the response is more than the limit.
• per_page is used to define the maximum amount of items one response can hold. There is an upper maximum (10000) for the parameter that cannot be exceeded.

To be able to traverse between pages more easily, the RELEX Data API also provides links to the subsequent pages. Each error response contains the following structure:

"_links": {
    "self": {
        "href": "/errors?request_id=2eb6aceb-731c-45f9-8427-41d6087c0983"
    },
    "next": {
        "href": "/errors?request_id=2eb6aceb-731c-45f9-8427-41d6087c0983&page=2"
    }
},

The href attribute under the _links.next attribute in the response body contains a relative URL for the next batch. When the next attribute is missing, there are no more batches available at present. However, asynchronicity means that there can be new items available in the next moment.

If there are no errors that meet the given query, the response is 200 OK with empty data array.

Disaster recovery (DR) is an organization’s ability to restore access and functionality to IT infrastructure after a disastrous event. These can range from natural disasters to human errors.

RELEX Data API uses active/hot-standby approach with a DNS-based traffic load balancer.

Hot-standby approach

Our approach involves two environments located in different geographical regions. Traffic is directed to a primary environment while the other is reserved for disaster recovery purposes. It utilises an active/hot-standby configuration, meaning that only one region is actively used to direct user traffic, while the other region remains ready but mostly inactive.

DNS-based traffic load balancer

During normal operations the load balancer routes the incoming traffic to the primary environment. In the event of a disaster the load balancer switches to the hot-standby environment.

Client considerations

In order to have a fast and optimal recovery from a disaster, it is crucial for clients to respect the ttl (time-to-live) sent by the DNS server. If the client caches the records too long, it can generate a long delay in the detection of the failover initiated by the load balancer. It is recommended to read through documentation for the programming language and the libraries that are used to access RELEX Data API to ensure expected behaviour.

The failover to secondary environment can take up to two minutes to avoid any unnecessary region switch-overs. If the disaster is generating failing requests (non-2xx status code returned), the clients must be ready to retry the failing requests as mentioned in Data processing and asynchronicity section

Disaster Recovery Testing

RELEX reserves the right to perform basic disaster recovery testing when necessary (approximately once a year). This is done to ensure that the best possible service is provided even during a disaster. These operations are designed not generate any traffic outage for clients, but there is a small risk due to the nature of the tests. Customers are always informed in advance before any DR practice takes place.

Disaster recovery for outbound endpoints

The same level of recovery existing for inbound will be reflected to outbound too, but due to the endpoints to be at the time of writing under active implementation, the DR actions might not work as expected.

This section describes the authentication methods and security-related requirements for the RELEX Data API.

The RELEX Data API utilizes Oauth 2.0 and OpenID Connect (OIDC) for authentication and authorization. OIDC is an authentication layer on top of OAuth 2.0​ and JSON Web Tokens (JWT).

The API is secured via a JWT access token, which must be present in each request. The JWT is fetched from a token endpoint of RELEX Identity (an Identity Provider) using a Client ID and a Client Secret.

Authorization steps

The RELEX Data API implements authorization using Client Credentials Grant. It is an authorization flow defined in the OAuth 2.0 specification, which is typically used for allowing access to resources in an automated context; that is, in a context with no human input.

The general steps involved are as follows:

1. Pre-requisites: Getting the information the client needs to request an access token, and configuring them to the client application. This is a one-time step.
2. Authorization: The client application requests an Access Token from RELEX Identity using the information provided in step 1.
3. Access: The client includes the provided Access Token in its requests, which allows it to access the RELEX Data API endpoints.

Pre-requisites

To authenticate with RELEX Identity, the client needs:

• A Client ID
• A Client Secret
• A RELEX Identity token endpoint URL

These are provided by RELEX during the implementation process. After this information has been provided, it needs to be configured into the client application according to the application's specific needs.

Authorization: Acquiring an Access Token from RELEX Identity

1. The client sends a POST request to the provided RELEX Identity token endpoint
   • Content type needs to be set to application/x-www-form-urlencoded
   • The Client ID, Client Secret, and client_credentials grant type must be included in the POST body as URL-encoded key-value pairs. An example body: client_id=my_client&client_secret=ZWFzdGVyZWdnCg&grant_type=client_credentials
2. RELEX Identity authenticates the client.
3. If authentication is successful, RELEX Identity authorizes the client by responding with a JSON object that contains:
   • "access_token": the JWT token that needs to be used for accessing the RELEX Data API
   • "expires_in": the access token's time to live in seconds
   • "token_type": information of how the token needs to be used, in this case, always set to "Bearer".
   • "scope": The scope that a token grants access to.

Accessing the RELEX Data API with tokens

Whenever the client accesses any RELEX Data API endpoint, the client must provide the following:

• A valid access token in an Authorization -header, preceded by Bearer. An example header is Authorization: Bearer eyJ[...]jw.

Access token expiry

When an Access Token expires, RELEX Data API calls respond with 401 Unauthorized The client application has two options to keep it authenticated:

• The client may handle 401 responses and react by initiating a new Client Credentials grant, as described in the "Authorization steps" section.
• The client may monitor the token's expiry interval. When the grant is about to expire, the client fetches a new token.

Note The Client Credentials grant type is not compatible with a construct such as refresh tokens, as mentioned in the protocol specification.

An example authorization flow

Client configuration

In our example flow, we have the following client-specific information:

• Client ID: hello-world
• Client Secret: ZWFzdGVyZWdnCg
• Token endpoint URL: https://identity.prod-eu.prod.cc.relexsolutions.com/login/restapi_uat/connect/token

For demonstration purposes, we'll use curl as a client.

Authorization

1. We POST our authorization request to the token endpoint.

% curl --location 'https://identity.prod-eu.prod.cc.relexsolutions.com/login/restapi_uat/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=hello-world' \
--data-urlencode 'client_secret=ZWFzdGVyZWdnCg'
[...]
> POST /login/restapi_uat/connect/token HTTP/1.1
> Host: identity.prod-eu.prod.cc.relexsolutions.com
> Accept: */*
> Content-Type: application/x-www-form-urlencoded
[...]
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=UTF-8
[...]

As a response body, we get the following:

{"access_token":"eyJ[...]jw","expires_in":3600,"token_type":"Bearer","scope":"example-scope"}

2. We extract the access token from the response field of the "access_token".
3. We use this token to access an API resource. In our case /data/master/locations:

% curl -vd "{ data: [...location objects...] }" -H "Content-Type: application/json" -H "Authorization: Bearer eyJ[...]jw" https://eu.rest.relexsolutions.com/example-customer/data/master/locations
> POST /example-customer/data/master/locations HTTP/1.1
> Host: eu.rest.relexsolutions.com
> Content-Type: application/json
> Authorization: Bearer eyJ[...]jw
[...]
< HTTP/1.1 202 Accepted
[...]

As an additional layer of security, the RELEX Data API can be configured to allow requests from only certain IP addresses or ranges. The recommendation is to always have an IP allowlist in place.

The API does not support an explicit blocklist.

Webhooks provide a push based way to get information about certain system events, e. g. about available data.

At the core webhooks are a POST request to a client-provided endpoint in contrast to polling the service endpoints with GET method.

The way to indicate that a webhook has been processed successfully is by returning a 2xx (status code 200-299) response to the webhook message within a reasonable time-frame (15s). If the endpoint does not respond in 15s then the retries will occur according to a predefined schedule (see the "Retry mechanism" section).

It's also important to disable CSRF protection for this endpoint since CSRF only works in client initiated requests and webhooks are by design initiated by the server.

Another important aspect of handling webhooks is to verify the signature and timestamp when processing them. You can learn more about it in the why "Verifying signature" section.

ℹ️ Only the metadata is sent to the endpoint. To get the actual data subsequent request to the rest-api should be executed.

Webhooks that did not get a 2xx response are retried according to an exponential backoff strategy as follows:

• immediately
• 5 seconds
• 5 minutes
• 30 minutes
• 2 hours
• 5 hours
• 10 hours
• 10 hours (in addition to the previous)

For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

ℹ️ The verification process could be omitted while developing and testing but the general advise is to implement validation from the start.

The reasons to verify incoming webhooks explained in this article by Svix - our webhook service provider:

Why Verify Webhooks (docs.svix.com)

To ensure the authenticity of incoming webhook the signature should be verified.

Type of the signature is HMAC where SHA-256 used as a hash function.

Every webhook contains following headers:

• SVIX-ID - the unique message identifier for the webhook message
• SVIX-TIMESTAMP - timestamp in seconds since epoch
• SVIX-SIGNATURE - the Base64 encoded list of signatures (space delimited)

To verify the webhook signature, use the preferred method:

1. Using the Svix SDK (Recommended)
   The recommended approach is to use the Svix SDK, as detailed in the official documentation:
   How to Verify Webhooks with the Svix Libraries.

2. Manual Verification (If SDK is Not an Option)
   If using the SDK is not possible, the signature can be verified manually by following these steps:
   Verifying Webhooks Manually.

The verification process requires the webhook headers, the webhook body, and an encoding secret provided by RELEX.

Here is an example of a request body sent with a webhook:

{
  "data": [
    {
      "id": "a123b456-c789-d012-e345-6789fghijk01",
      "resource": "sales_forecasts",
      "timestamp": "2024-04-03T07:15:22.567Z",
      "url": "/data/transactions/sales_forecasts/a123b456-c789-d012-e345-6789fghijk01"
    },
    {
      "id": "fefa31ba-ec6a-3f60-bdc2-3f10a6afc55f",
      "resource": "sales_forecasts",
      "timestamp": "2024-04-03T08:20:39.123Z",
      "url": "/data/transactions/sales_forecasts/fefa31ba-ec6a-3f60-bdc2-3f10a6afc55f"
    }
  ],
  "meta": {
    "created_at": "2024-04-03T09:10:19.821Z",
    "type": "data.transactions.notify"
  }
}

where:

data (array of resources): Each object represents an available data resource.

• id → Unique identifier for the resource.
• resource → Resource name (e.g., sales_forecasts).
• timestamp → When the data was made available (ISO 8601 format).
• url → Relative path to the resource.

meta (Webhook Metadata): Provides context for the webhook event.

• created_at → When the webhook message was created.
• type → Type of event in the format data.<namespace>.notify. The <namespace> is related to the resource category and can be, for example, custom.

Webhooks from RELEX are delivered through Svix, which operates using a predefined set of static IP address ranges. If your webhook receiving endpoint is protected by a firewall or subject to network-level filtering, ensure that traffic from RELEX’s webhook delivery service is explicitly allowed.

The up-to-date list of source IPs used by Svix is maintained at the following location:

https://docs.svix.com/receiving/source-ips

The namespace for metadata contains the different endpoints for API metadata.

The namespace for master data contains the different endpoints for transferring master data.