Webhook Discussion

[mahatoankitkumar]

Table structure - (### Updated)

• name TEXT PRIMARY KEY (Name to identify the webhook's purpose)

• description TEXT NOT NULL (description of the webhook)

• enabled BOOLEAN NOT NULL DEFAULT true (Whether the webhook is currently active)

• url TEXT NOT NULL (The destination URL where the webhook will send requests)

• method TEXT NOT NULL DEFAULT 'POST' (HTTP method (POST, GET, etc.))

• version TEXT NOT NULL (To generate the payload in multiple formats.)

• auth_config json (Authentication credentials/tokens)

• events TEXT[] check (array_position(events, null) is null) ( Events/topics that trigger this webhook)

• max_retries INTEGER NOT NULL DEFAULT 0 (Maximum number of retry attempts for failed webhooks, currently can be set to 0 till we have retry logic implemented)

• last_triggered_at TIMESTAMP (When the webhook was last triggered)

• created_by TEXT NOT NULL

• created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP

• updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP

---

authConfig can be something like this but how do store these username, password, tokens?

enum AuthConfig {
    Basic {
        username: String,
        password: String,
    },
    Bearer {
        token: String,
    },
    Custom {
        key_name: String,
        token: String,
    },
}

---

API Structure -

1. Create a Webhook
   Endpoint: POST /webhooks
   { "name": "test", "description": "Triggered on experiment created", "enabled": true, "url": "https://example.com/webhook", "method": "POST", "custom_headers": {"x-tenant": "dev"}, "service_headers": [configVersion], "authorization": {"Auth": "Bearer token123"}, "events": ["ExperimentCreated"], "max_retries": 0 }
   Response: 201 Created (Webhook)

2. Get a List of Webhooks
   Endpoint: GET /webhooks
   Response: 200 OK ([Webhook])

3. Get a Single Webhook
   Endpoint: GET /webhooks/{id}
   Response: 200 OK (Webhook)

4. Update a Webhook
   Endpoint: PUT /webhooks/{id}
   { "name": "test", "description": "Triggered on experiment updated", "enabled": true, "url": "https://example.com/webhook2", "method": "POST", "custom_headers": {"x-tenant": "dev"}, "service_headers": [configVersion], "authorization": {"Auth": "Bearer token123"}, "events": ["ExperimentUpdated"], "max_retries": 0 }
   Response: 200 OK (Webhook)

5. Delete a Webhook
   Endpoint: DELETE /webhooks/{id}
   Response:204 No Content

[knutties]

@mahatoankitkumar - the stripe webhook reference is a good one - you have covered most of them.

1. Should we add API version (in case we need to generate the payload in multiple formats - based on the readiness of the merchant) ?
2. Does this mean we can call multiple webhook endpoints per event or the application will do the check if there is already a webhook associated with this endpoint ?
3. Service headers field is not that intuitive (we should add it always right - why does client have to choose this) ?

[mahatoankitkumar]

Should we add API version (in case we need to generate the payload in multiple formats - based on the readiness of the merchant) ?

Did thought of this, Can be added

Does this mean we can call multiple webhook endpoints per event or the application will do the check if there is already a webhook associated with this endpoint ?

Yes the application can check that while creation of the webhook

Service headers field is not that intuitive (we should add it always right - why does client have to choose this) ?

Yeah agree

[pratikmishra356]

I am not getting clear picture of version usage here ,
As implemented currently we expect version for every webhook row , and default is hardcoded as "V1"
@knutties according to you version corresponds to url/api being used in a particular webhook , if external application want to support multiple version which means multiple webhook rows , then that will be captured in name itself because its unique

else we can change from version to api_version

if it is for payload then can we rename to payload_version

[mahatoankitkumar]

@pratikmishra356 version here is for payload version, which at the moment is just one

[knutties]

It is payload_version basically captures payload structure version to solve for multiple structures during evolution.

[mahatoankitkumar]

@knutties Do we need
metadata (Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.)
and
secrets (The endpoint’s secret, used to generate webhook signatures. Only returned at creation.) as columns here?
And was thinking do we need both enabled and status or we can eliminate one?