Skip to main content

Webhook guidelines

If you follow the Corvina applications guide, you will see that Corvina platform provides a webhook to notify your application when a new event occurs (installation and uninstallation are examples of that).

Each time Corvina platform sends a notification to your application, it will send a POST request to the webhook URL you provided. The request will contain a JSON payload with the event details (so the content-type is application/json). The request will also contain an Authorization header that contains a signed JWT token that you should verify using the public key provided by Corvina platform.

Security​

The webhook is a public endpoint, so you should take care of the security of your application and do not trust any request the endpoint could receive. We recommend to validate the Authorization header and the payload signature using the public key provided by the Corvina platform, available in the openIdConfigurationUrl property in the installation payload.

An example of a (decoded) legitimate token you should receive is the following

{
  "exp": 1741346339,
  "iat": 1741345439,
  "jti": "a66b4b8d-9462-4794-9f21-616d5fbb4c9f",
  "iss": "https://auth.corvina.io/auth/realms/sample1",
  "sub": "d5b28851-3cf4-4108-bf44-590b042692a8",
  "typ": "Bearer",
  "azp": "core", // validate to match "core"
  "acr": "1",
  "scope": "app:corvina-app-nodered@myorg event:installed" // validate both app: and event:
}

You have to verify that Authorized Parties (azp) matches core, which is the name of the service in charge of the app lifecycle.
Then, you have to validate the scopes, splitting first by whitespaces and then by colons:

  • app: is a fixed key to indicate the app and the organization it is intended for, joined by an at sign (@)
  • event: is the key to identify the event, that is the eventType field
warning

Validate fields and signature!

Retry policy​

If your application is not available when Corvina platform sends a notification, Corvina platform will retry the notification 3 times with an exponential backoff. Currently the retry policy is configured to retry after 1, 3 and 9 seconds (but we reserve to slightly change that in the future).

We execute a retry only if the response status code is 429 or 5xx. If the response status code is 4xx, we don't retry.

Timeout​

The timeout for the webhook is 7 seconds. If your application takes more than 7 seconds to process the notification, Corvina platform will consider the notification as successful and will not retry it.

tip

It's perfectly fine if your application needs more time to process the notification to execute the processing in a background job and return a 202 response code. This way Corvina platform will not retry the notification. If you want a most reliable way to process the notification, you can use an internal queue system instead of a background job.