github.com/treeverse/lakefs@v1.24.1-0.20240520134607-95648127bfb0/docs/howto/hooks/webhooks.md (about)

     1  ---
     2  title: Webhooks
     3  parent: Actions and Hooks
     4  grand_parent: How-To
     5  description: Webhooks reference
     6  redirect_from:
     7     - /hooks/webhooks.html
     8  ---
     9  
    10  # Webhooks
    11  
    12  {% include toc.html %}
    13  
    14  A Webhook is a Hook type that sends an HTTP POST request to the configured URL.
    15  Any non 2XX response by the responding endpoint will fail the Hook, cancel the execution of the following Hooks
    16  under the same Action. For `pre-*` hooks, the triggering operation will also be aborted.
    17  
    18  **Warning:** You should not use `pre-*` webhooks for long-running tasks, since they block the performed operation.
    19  Moreover, the branch is locked during the execution of `pre-*` hooks, so the webhook server cannot perform any write operations on the branch (like uploading or commits).
    20  {: .note }
    21  
    22  ## Action File Webhook properties
    23  
    24  _See the [Action configuration](./index.md#action-file) for overall configuration schema and details._
    25  
    26  | Property     | Description                                            | Data Type                                                                                 | Required | Default Value | Env Vars Support |
    27  |--------------|--------------------------------------------------------|-------------------------------------------------------------------------------------------|----------|---------------|------------------|
    28  | url          | The URL address of the request                         | String                                                                                    | true     |               | no               |
    29  | timeout      | Time to wait for response before failing the hook      | String (golang's [Duration](https://golang.org/pkg/time/#Duration.String) representation) | false    | 1 minute      | no               |
    30  | query_params | List of query params that will be added to the request | Dictionary(String:String or String:List(String)                                           | false    |               | yes              |
    31  | headers      | Headers to add to the request                          | Dictionary(String:String)                                                                 | false    |               | yes              |
    32  
    33  **Secrets & Environment Variables**<br/>
    34  lakeFS Actions supports secrets by using environment variables.
    35  The format `{% raw %}{{{% endraw %} ENV.SOME_ENV_VAR {% raw %}}}{% endraw %}` will be replaced with the value of `$SOME_ENV_VAR`
    36  during the execution of the action. If that environment variable doesn't exist in the lakeFS server environment, the action run will fail.
    37  
    38  All environment variables need to begin with "LAKEFSACTIONS_". Otherwise, they will be blocked.
    39  Additionally, the `actions.env.enabled` configuration parameter can be set to `false` to block access to all environment variables.
    40  {: .note }
    41  
    42  Example:
    43  
    44  ```yaml
    45  ...
    46  hooks:
    47    - id: prevent_user_columns
    48      type: webhook
    49      description: Ensure no user_* columns under public/
    50      properties:
    51        url: "http://<host:port>/webhooks/schema"
    52        timeout: 1m30s
    53        query_params:
    54          disallow: ["user_", "private_"]
    55          prefix: public/
    56        headers:
    57          secret_header: "{% raw %}{{{% endraw %} ENV.MY_SECRET {% raw %}}}{% endraw %}"
    58  ...
    59  ```
    60  
    61  ## Request body schema
    62  Upon execution, a webhook will send a request containing a JSON object with the following fields:
    63  
    64  | Field               | Description                                                       | Type   |
    65  |---------------------|-------------------------------------------------------------------|--------|
    66  | event_type          | Type of the event that triggered the _Action_                     | string |
    67  | event_time          | Time of the event that triggered the _Action_ (RFC3339 formatted) | string |
    68  | action_name         | Containing _Hook_ Action's Name                                   | string |
    69  | hook_id             | ID of the _Hook_                                                  | string |
    70  | repository_id       | ID of the Repository                                              | string |
    71  | branch_id[^1]       | ID of the Branch                                                  | string |
    72  | source_ref          | Reference to the source on which the event was triggered          | string |
    73  | commit_message[^2]  | The message for the commit (or merge) that is taking place        | string |
    74  | committer[^2]       | Name of the committer                                             | string |
    75  | commit_metadata[^2] | The metadata for the commit that is taking place                  | string |
    76  | commit_id[^2,^4]    | The ID of the commit that is being created              | string |
    77  | tag_id[^3]          | The ID of the created/deleted tag                                 | string |
    78  
    79  [^1]: N\A for Tag events  
    80  [^2]: N\A for Tag and Create/Delete Branch events  
    81  [^3]: Applicable only for Tag events
    82  [^4]: Applicable to commit/merge events. For merges, this represents the merge commit ID to be created if the merge operation succeeds.
    83  
    84  Example:
    85  ```json
    86  {
    87    "event_type": "pre-merge",
    88    "event_time": "2021-02-28T14:03:31Z",
    89    "action_name": "test action",
    90    "hook_id": "prevent_user_columns",
    91    "repository_id": "repo1",
    92    "branch_id": "feature-1",
    93    "source_ref": "feature-1",
    94    "commit_message": "merge commit message",
    95    "commit_id": "5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",
    96    "committer": "committer",
    97    "commit_metadata": {
    98      "key": "value"
    99    }
   100  }
   101  ```