Webhook Subscriptions

Webhooks allow integrated applications to be notified when an event occurs in VOCUS. This functionality is currently available for FlightRisk Risk Assessments.

/WebhookSubscriptions/

HTTP POST Service Account

Creates or updates a webhook subscription. The subscription is automatically scoped to the domain to which the service account belongs, and will only notify the callback URL for events within the service account's scope.

The subscription's properties may be updated at any time by calling this endpoint. This will not create a different subscription.

Input

Field	Type	Constraints	Detail
eventNames	String Array	Required	Supported Values: FlightRisk.RiskAssessmentExecuted
url	String	Required	A publicly-routable URL for VOCUS to call when the event occurs.
sharedSecret	String	Required 64-1024	The value that VOCUS will use to sign the authorization header when calling the URL. This value should be cryptographically random, and may be rotated at any time by calling this endpoint.

Sample Payload

        // register to be notified when a risk assessment is run for legs within the scope of the service account
        const payload = {
            eventNames: ["FlightRisk.RiskAssessmentExecuted"],
            url: "https://example.org/url-to-notify",
            sharedSecret: "A_LONG_CRYPTOGRAPHICALLY_STRONG_VALUE"
        };

Output

See HTTP Response Codes

HTTP Status	Data
200

Webhook Callback Details

When VOCUS notifies the callback URL, the request will follow a specific structure.

Request Structure from VOCUS

Method: POST
Content-Type: application/json
Authorization Header: Contains a JWT signed with shared secret.
Body: JSON payload containing the event data.
Timeout: 15 seconds

Authorization Header Details

The authorization header will be in this format: Authorization: Token <JWT_TOKEN>

The JWT token will be signed with the shared secret used to register the webhook subscription.

Token will contain claims:

payloadHash - SHA-256 hash of the request body
iat - Issued at time
exp - Expiration time
nbf - Not before time

Validation Process

To validate incoming webhook requests:

Extract the JWT token from the Authorization header.
Verify the JWT signature using shared secret.
Check that the token has not expired.
Extract the payloadHash claim.
Compute the SHA-256 hash of the request body.
Verify that the computed hash matches the payloadHash claim.
Parse and process the JSON payload.

Retry Behavior

If the webhook endpoint returns an error or is unreachable, VOCUS will automatically retry the webhook delivery with the following schedule:

Retry 1: 30 seconds after initial failure
Retry 2: 1 minute after first retry
Retry 3: 2 minutes after second retry
Retry 4: 5 minutes after third retry

The total retry period spans approximately 8.5 minutes. After the final retry attempt, VOCUS will stop attempting delivery for that specific event.

Retries are only attempted for HTTP errors that suggest temporary problems (such as 5xx server errors or network timeouts). Authentication failures (4xx errors) will not be retried.

Sample Event Payload

When a FlightRisk.RiskAssessmentExecuted event occurs, the JSON payload will contain:

        // Example payload for FlightRisk.RiskAssessmentExecuted event
        {
            "legIds": ["EXTERNAL_LEG_ID_12345", "EXTERNAL_LEG_ID_67890"]
        }

Error Handling

The webhook callback endpoint should:

Respond with HTTP 200 when the webhook is successfully processed
Respond with HTTP 401 for authentication/validation failures (will not be retried)
Respond with HTTP 500 for temporary processing errors (VOCUS will retry)