Skip to content

Commit

Permalink
docs: add documentation for webhook
Browse files Browse the repository at this point in the history
  • Loading branch information
bthari committed Sep 26, 2024
1 parent 7caf48a commit 4f84153
Showing 1 changed file with 75 additions and 0 deletions.
75 changes: 75 additions & 0 deletions docs/user/templates/webhook/01_webhook_config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
<!-- page-title: Webhook -->

# Webhook

When an event happens (e.g. creating new model's version, deploy endpoint), we might want to trigger action in other services, Merlin provides a way this by triggering a webhook call.
The webhook that will be called is configured per event type, and it could contain multiple endpoints which can be configured as synchronous or asynchronous call.

For the detail of available configuration please refer to [MLP library docs](https://github.com/caraml-dev/mlp/blob/main/api/pkg/webhooks/README.md), this documentation will only cover the basic config and the paylod of webhook which we has implemented.

## 1. Webhook Configuration
In Merlin's yaml for config you can add new field for the webhook's configuration which will looks like this:
```yaml
WebhooksConfig:
Enabled: true
Config:
on-model-version-deployed:
- URL: http://127.0.0.1:8000/async-webhook
Method: POST
Async: true
Name: async
on-model-version-undeployed:
- URL: http://127.0.0.1:8000/sync-webhook
Method: POST
FinalResponse: true
Name: sync
```
## 2. Webhook Events and Payload
### 2.1. Model Version's Endpoint
**Events:**
- `on-model-version-predeployment`: will be triggered before the version endpoint is deployed, if the sync webhook return an error (non `200` response), the deployment will be **aborted**. The successful response of this webhook will not affect the deployment process, as we do not process the response
- `on-model-version-deployed`: will be triggered after the version endpoint is successfully deployed (either new or updated)
- `on-model-version-undeployed`: will be triggered after the version endpoint is successfully undeployed

**Request Payload**
```json
{
"event_type": "{event type}",
"version_endpoint": "{version endpoint object}"
}
```

Examples:
```json
{
"event_type": "on-model-version-predeployment",
"version_endpoint": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"version_id": 0,
"status": "pending",
...
}
}
```

For the the complete field `version_endpoint` please refer to our [swagger docs](https://github.com/caraml-dev/merlin/blob/main/swagger.yaml).

**Response**

As of writing this document (25 September 2024) and mentioned previously, the successful response will not affect the process of our deployment. But for future usage, we're expecting the response of the final synchronous webhook that will be called to be in the following format:

Successful Response:
```json
{
"code": "200",
"version_endpoint": "{version endpoint object}"
}
```

Error response:
```json
{
"code": "{error code}",
"message": "{reason for error}"
}
```

0 comments on commit 4f84153

Please sign in to comment.