Policies

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

  1. publisher’s authorization: security validations to ensure that only authorized publishers can send events to Events Hub;

  2. 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:

  1. number of attempts (up to 10 times);

  2. HTTP status code that triggers a new attempt;

  3. 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:

  1. click on the button +;

  2. fill in the Name and Description (optional). The name must be unique. It is not possible to create two policies with the same name;

  3. 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.
      policies ip filtering

  • 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.
    policies oauth

  • 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 edit icon;

  • deactivate them by clicking on the desativa policy 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

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]