Skip to content

Event notifications validation handshake #565

@rartych

Description

@rartych

Problem description
In the current guide document we have

To protect the sender, CloudEvents specification provides some guidance there: https://github.com/cloudevents/spec/blob/main/cloudevents/http-webhook.md#4-abuse-protection

Event Producers SHALL choose based on their internal security guidelines to implement measures based on the above guidance to ensure abuse protection. For e.g., An event producer might ask the subscriber to pre-register the notification URL at the time of app onboarding. If this registered notification URL doesn't match later with the notification URL in the request, the event producer can choose to reject the request with the relevant error code.

Possible evolution

The referenced guidance HTTP 1.1 Web Hooks for Event Delivery - Version 1.0 proposes validation handshake that looks like that:

sequenceDiagram
    participant Sender as Event Sender
    participant Target as Event Sink (Webhook)

    Note over Sender, Target: CloudEvents HTTP webhook validation handshake for abuse protection

    Sender->>Target: OPTIONS
    Note right of Sender: Headers:<br>- WebHook-Request-Origin: <DNS expression><br>- WebHook-Request-Callback: <optional-Sender-validation-URL><br>- WebHook-Request-Rate: <optional-requested-rate>

    alt Target grants permission
        Note right of Target: Validates origin and callback URL<br>Decides allowed rate if applicable
        Target-->>Sender: 200 OK
        Note left of Target: Headers:<br>- WebHook-Allowed-Origin: <DNS expression><br>- WebHook-Allowed-Rate: <allowed-rate (optional)>
    else Target denies permission
        Target-->>Sender: 403 Forbidden or other error status
        Note left of Target: Rejects subscription validation
    end

    Note over Sender, Target: On success, Sender proceeds with POST requests (events)
    Sender->>Target: POST
 Note right of Sender:  Headers: <br> Content-Type: application/cloudevents+json <br> Origin: <Event Sender> <br> X-correlator:
    Target-->>Sender: 200 OK or relevant response
Loading

Should the handshake be applied for CAMARA event notifications globally or left for agreement for example at the time of app onboarding?

Alternative solution

Additional context
The Notification Authentication flows are discussed in issue #461

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions