Policies

Policies are a tool for managing two aspects of the receiving and distributing events process:

publisher’s authorization: security validations to ensure that only authorized publishers can send events to Events Hub;
event delivery: the automatic attempts that the system must make if the first send of an event fails.

Listing policies

The Policies screen displays all existing policies in order of creation. In the Order by field, you select the order you want between:

Creation (desc): default. Lists policies from the most recent creation date to the oldest.
Creation (asc): lists policies from the oldest creation date to the latest.
Name (desc): lists policies in alphabetical order, from Z to A.
Name (asc): lists policies in alphabetical order, from A to Z.

You can also search for policies by name.

The DETAILS column contains the expand icon icon expand , which displays the settings of the selected policy.

The ACTIONS column contains icons for editing icon edit and deleting icon delete policies.

policies details

Security options

Interceptors are used to authorize publishers. There are five types available:

Access Token Validation
Client ID Validation
OAuth Validation
JWT Validation
IP Filtering Validation

The authorization endpoints are defined by contexts on the Authorizations screen. It has two sections:

OAUTH: for the interceptors OAuth Validation, Client ID Validation and Access Token Validation;
JWT: for the JWT Validation interceptor.

The use of security interceptors is optional. However, if you add policies to your handler, you need to configure the Authorization URL linked to the interceptor. Except for "IP Filtering Validation," all others depend on this configuration to work. If you are using the Sensedia API Platform for this, here’s how to obtain the authorization URL.

Automatic delivery retries

When the first attempt to deliver an event to a subscriber fails, Events Hub can retry the delivery, following the settings configured by the user. These settings include:

number of attempts (up to 10 times);
HTTP status code that triggers a new attempt;
the request timeout.

The Events Hub tries to resend events until it succeeds or reaches the number of automatic attempts defined in the settings. To increase the chances of successful delivery, we use the exponential backoff algorithm. This means that the system waits an increasingly long time between attempts, avoiding network congestion.

If all automatic attempts fail, you can try manual delivery via the Delivery Retry screen.

Creating a policy

To create a new policy:

click on the button +;
fill in the Name and Description (optional). The name must be unique. It is not possible to create two policies with the same name;
If you want, set security and delivery options for the policy. See below:

Security

The HANDLER PUBLISHER SECURITY FLOW section includes the security interceptors that can be added to the flow.

See how to use the Sensedia API Platform to provide publisher authorization.

To include an interceptor, click on the icon add icon next to its name. You can add more than one:

Access Token Validation: validates an access token passed in the request. When you select it, you must enter
- Location: where the access token will be passed, it can be any (all locations will be checked); cookie; header; header or cookie; or query param.
- Name: the name with which the access token value will be passed.
Client ID Validation: validates a client ID passed in the request. When you select it, you must enter:
- Location: where the client ID will be passed, it can be any (all locations will be checked); cookie; header; header or cookie; or query param.
- Name: the name with which the value of the client ID will be passed.
IP Filtering Validation: list of IPs that can or cannot send requests.
- In the List Type field, you can choose between:
  - Block List: list of IPs that will have their requests blocked; or
  - Allow List: list of the only IPs that will be able to send requests.
- IP List: to include the IPs. You must separate them by comma.
OAuth Validation: validates client_id and access_token passed in request headers. The URL that provides validation must be included on the Authorizations page and there are no fields to configure.
JWT Validation: validates JWT tokens (which must be sent in the Bearer standard) passed in the request.
The URL that provides validation must be included on the Authorizations page. When selecting this interceptor, you must enter:
- Location: where the token will be passed; options: header; default JWT header; or query param.
- Name: the name under which the token value will be passed.

The selected interceptors are shown in the Execution Flow section. If you wish, you can:

edit them by clicking on the icon;
deactivate them by clicking on the icon;
reorder them by clicking on the interceptor and dragging it to the desired position.
The validations will take place in the order they appear on the screen. If any of them fails, the request is interrupted.

policies flow

Delivery settings

The Delivery Settings section defines the maximum number of automatic resend attempts and the status codes that will trigger these attempts.

Configure the fields:

Automatic Retry Quantity: the number of automatic attempts that will be made if the first delivery fails. Up to 10;
Requisition Timeout: time limit for waiting for the response of the subscriber’s URL after each delivery attempt. Up to 30 seconds;
Status Code for Automatic Retry: HTTP return status codes that should trigger an automatic attempt.
- If entering more than one, separate them with a comma.
- If you want to register a code family, use "xx": 4xx, 5xx.
- Codes from the 200 family are not accepted in this field. This is because a 2xx response means that the event was delivered successfully and does not need to be sent again.

policies retry settings

Recommended status codes

The Status Code for Automatic Retry field allows you to include codes from the 400 and 500 family. However, not all of them make sense for retry. In the tables below, we detail which are recommended and which are not:

**Recommended**
Status code	Description	Retry makes sense?	Reason
408	Request Timeout	Yes	The server did not respond in time.
429	Too Many Requests	Yes	The user sent too many requests in a certain period.
500	Internal Server Error	Yes	A generic code indicating server failure. This failure can occur due to temporary load spikes.
502	Bad Gateway	Yes	An intermediate server received an invalid response from an upstream server.
503	Service Unavailable	Yes	The server is not ready to process the request. This can be caused by maintenance or overload.
504	Gateway Timeout	Yes	The intermediate server did not respond in time.

**Not recommended**
Status code	Description	Retry makes sense?	Reason
400	Bad Request	No	The request was poorly formulated. Retrying the same request will result in the same error.
401	Unauthorized	No	Authentication is required or has failed. Retrying will not solve the issue without proper authentication.
403	Forbidden	No	The client does not have permission to perform the action. There is no reason to retry.
404	Not Found	No	The requested resource was not found. Retrying will not bring the expected response.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]