> ## Documentation Index > Fetch the complete documentation index at: https://docs.siftstack.com/llms.txt > Use this file to discover all available pages before exploring further. # webhooks > sift/webhooks/v1/webhooks.proto ## Services *RPC methods exposed by this API.* ### WebhookService | Method | Request | Response | Description | | :---------------------------------- | :---------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GetWebhook | [GetWebhookRequest](#getwebhookrequest) | [GetWebhookResponse](#getwebhookresponse) | Retrieve a webhook by ID. | | CreateWebhook | [CreateWebhookRequest](#createwebhookrequest) | [CreateWebhookResponse](#createwebhookresponse) | Create a webhook. | | UpdateWebhook | [UpdateWebhookRequest](#updatewebhookrequest) | [UpdateWebhookResponse](#updatewebhookresponse) | Update select fields of an existing webhook. | | ListWebhooks | [ListWebhooksRequest](#listwebhooksrequest) | [ListWebhooksResponse](#listwebhooksresponse) | Retrieve and optionally filter a list of webhooks. | | TestWebhook | [TestWebhookRequest](#testwebhookrequest) | [TestWebhookResponse](#testwebhookresponse) | Test an existing webhook or a webhook create request. This RPC will attempt to send an actual webhook with the provided parameters and forward back the response from the target. | | CreateWebhookSignatureKey | [CreateWebhookSignatureKeyRequest](#createwebhooksignaturekeyrequest) | [CreateWebhookSignatureKeyResponse](#createwebhooksignaturekeyresponse) | Create an webhook signature key. If a webhook signature key is active, the bodies of all webhooks will be signed using the signature key with HMAC-SHA-256. The signature generated will then included in the `X-Sift-Signature` HTTP header. Only one key can be held per organization. If an existing key exists, then this will simply return it. See `WebhookService_RotateWebhookSignatureKey` to rotate the key. | | GetWebhookSignatureKey | [GetWebhookSignatureKeyRequest](#getwebhooksignaturekeyrequest) | [GetWebhookSignatureKeyResponse](#getwebhooksignaturekeyresponse) | Retrieve the current webhook signature key. Will return a not found error if one doesn't yet exist. | | ToggleWebhookSignatureKeyActivation | [ToggleWebhookSignatureKeyActivationRequest](#togglewebhooksignaturekeyactivationrequest) | [ToggleWebhookSignatureKeyActivationResponse](#togglewebhooksignaturekeyactivationresponse) | Set the activation state of the organization's current webhook signature key. Will return a not found error if one doesn't yet exist. | | RotateWebhookSignatureKey | [RotateWebhookSignatureKeyRequest](#rotatewebhooksignaturekeyrequest) | [RotateWebhookSignatureKeyResponse](#rotatewebhooksignaturekeyresponse) | Generate a new webhook signature key and replace the previous one. The activation state of the new key will match the activation state of the previous. | | BatchCreateWebhookLogs | [BatchCreateWebhookLogsRequest](#batchcreatewebhooklogsrequest) | [BatchCreateWebhookLogsResponse](#batchcreatewebhooklogsresponse) | Create a batch of webhook logs. Users should not have to call this directly. | | ListWebhookLogs | [ListWebhookLogsRequest](#listwebhooklogsrequest) | [ListWebhookLogsResponse](#listwebhooklogsresponse) | Retrieve and optionally filter a list of webhook logs. | ## Messages *Data models used across requests/responses.* ### BatchCreateWebhookLogsRequest The request for a call to `WebhookService_BatchCreateWebhookLogs` to create a batch of webhook logs. | Field | Type | Label | Description | | :------- | :-------------------------------------------------- | :------- | :---------- | | requests | [CreateWebhookLogRequest](#createwebhooklogrequest) | repeated | | ### BatchCreateWebhookLogsResponse The response of a call to `WebhookService_BatchCreateWebhookResponse`. *This message has no fields.* ### CreateWebhookLogRequest Request to create a single webhook log entry. | Field | Type | Label | Description | | :--------------------- | :------------------------------------ | :------- | :---------- | | webhook\_id | string | | | | event\_id | string | | | | retry\_attempt\_number | uint32 | | | | status | [WebhookLogStatus](#webhooklogstatus) | | | | payload | string | optional | | | error\_reason | string | optional | | | sent\_date | google.protobuf.Timestamp | | | ### CreateWebhookRequest The request for a call to `WebhookService_CreateWebhook` to create a webhook. | Field | Type | Label | Description | | :------------ | :-------------------------------------- | :------- | :---------- | | name | string | | | | target\_url | string | | | | event\_type | [WebhookEventType](#webhookeventtype) | | | | payload | string | optional | | | http\_headers | [WebhookHttpHeader](#webhookhttpheader) | repeated | | ### CreateWebhookResponse The response of a call to `WebhookService_CreateWebhook`. | Field | Type | Label | Description | | :------ | :------------------ | :---- | :---------- | | webhook | [Webhook](#webhook) | | | ### CreateWebhookSignatureKeyRequest The request for a call to `WebhookService_CreateWebhookSignatureKey` to create a webhook signature key. *This message has no fields.* ### CreateWebhookSignatureKeyResponse The response for a call to `WebhookService_CreateWebhookSignatureKey`. The `active` field indicates whether or not whether the key is currently active. | Field | Type | Label | Description | | :------------- | :------------------------------------------ | :---- | :---------- | | signature\_key | [WebhookSignatureKey](#webhooksignaturekey) | | | ### GetWebhookRequest The request for a call to `WebhookService_GetWebhook` to retrieve a webhook. | Field | Type | Label | Description | | :---------- | :----- | :---- | :---------- | | webhook\_id | string | | | ### GetWebhookResponse The response of a call to `WebhookService_GetWebhook`. | Field | Type | Label | Description | | :------ | :------------------ | :---- | :---------- | | webhook | [Webhook](#webhook) | | | ### GetWebhookSignatureKeyRequest The request for a call to `WebhookService_GetWebhookSignatureKey` to retrieve the current webhook signature key. | Field | Type | Label | Description | | :--------------- | :----- | :---- | :------------------------ | | organization\_id | string | | Optional organization ID. | ### GetWebhookSignatureKeyResponse The response for a call to `WebhookService_GetWebhookSignatureKey`. The `active` field indicates whether or not whether the key is currently active. | Field | Type | Label | Description | | :------------- | :------------------------------------------ | :---- | :---------- | | signature\_key | [WebhookSignatureKey](#webhooksignaturekey) | | | ### ListWebhookLogsRequest The request for a call to `WebhookService_ListWebhookLogs` to retrieve and filter webhook logs. | Field | Type | Label | Description | | :---------- | :----- | :---- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page\_size | uint32 | | The maximum number of webhook logs to return. The service may return fewer than this value. If unspecified, at most 50 runs will be returned. The maximum value is 1000. | | page\_token | string | | A page token, received from a previous `ListWebhookLogs` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListWebhookLogs` must match the call that provided the page token. | | filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. The available fields to filter by are `webhook_id`, `status`. | | order\_by | string | | How to order the retrieved webhook logs. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available field to order\_by is `created_date`. If left empty, items are ordered by `created_date` in ascending order (oldest-first). For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date desc" | ### ListWebhookLogsResponse The response of a call to `WebhookService_ListWebhookLogsResponse`. | Field | Type | Label | Description | | :---------------- | :------------------------ | :------- | :---------- | | logs | [WebhookLog](#webhooklog) | repeated | | | next\_page\_token | string | | | ### ListWebhooksRequest The request for a call to `WebhookService_ListWebhooks` to retrieve and filter webhooks. | Field | Type | Label | Description | | :---------- | :----- | :---- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page\_size | uint32 | | The maximum number of webhooks to return. The service may return fewer than this value. If unspecified, at most 50 runs will be returned. The maximum value is 1000. | | page\_token | string | | A page token, received from a previous `ListWebhooks` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListWebhooks` must match the call that provided the page token. | | filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are `webhook_id`, `name`, `event_type`, `is_archived`, and `archived_date`. | | order\_by | string | | How to order the retrieved webhooks. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available field to order\_by is `created_date`. If left empty, items are ordered by `created_date` in ascending order (oldest-first). For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date desc" | ### ListWebhooksResponse The response of a call to `WebhookService_ListWebhooks`. | Field | Type | Label | Description | | :---------------- | :------------------ | :------- | :---------- | | webhooks | [Webhook](#webhook) | repeated | | | next\_page\_token | string | | | ### RotateWebhookSignatureKeyRequest The request for a call to `WebhookService_RotateWebhookSignatureKey` replace the current webhook signature key with a new one. The activation state of the new signature key will be inherited from the previous key. If no key exists then this will return an error - see `WebhookService_CreateWebhookSignatureKey`. *This message has no fields.* ### RotateWebhookSignatureKeyResponse The response for a call to `WebhookService_RotateWebhookSignatureKey`. The `active` field indicates whether or not whether the key is currently active. | Field | Type | Label | Description | | :------------- | :------------------------------------------ | :---- | :---------- | | signature\_key | [WebhookSignatureKey](#webhooksignaturekey) | | | ### TestWebhookRequest The request for a call to `WebhookService_TestWebhook` to test an existing webhook or a webhook create request. | Field | Type | Label | Description | | :-------------------------- | :-------------------------------------------- | :---- | :---------- | | oneof form. webhook\_id | string | | | | oneof form. webhook | [Webhook](#webhook) | | | | oneof form. create\_request | [CreateWebhookRequest](#createwebhookrequest) | | | ### TestWebhookResponse The response of a call to `WebhookService_TestWebhook`. The response code and body will come from the HTTP response from the target URL. | Field | Type | Label | Description | | :------------------- | :----- | :---- | :---------- | | http\_response\_code | uint32 | | | | http\_response\_body | bytes | | | ### ToggleWebhookSignatureKeyActivationRequest The request for a call to `WebhookService_ToggleWebhookSignatureKeyActivation` to enable or disable the current webhook signature key. Set `enable` to `true` to activate the signature key, and `false` to deactivate. | Field | Type | Label | Description | | :----- | :--- | :---- | :---------- | | enable | bool | | | ### ToggleWebhookSignatureKeyActivationResponse The response for a call to `WebhookService_ToggleWebhookSignatureKeyActivation`. | Field | Type | Label | Description | | :------------- | :------------------------------------------ | :---- | :---------- | | signature\_key | [WebhookSignatureKey](#webhooksignaturekey) | | | ### UpdateWebhookRequest The request for a call to `WebhookService_UpdateWebhook` to update a webhook. | Field | Type | Label | Description | | :----------- | :------------------------------------------------------ | :---- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | webhook | [Webhook](#webhook) | | The webhook to update. The webhook's `webhook_id` field is used to identify the webhook to update and is required. | | update\_mask | [google.protobuf.FieldMask](#google-protobuf-fieldmask) | | The list of fields to be updated. The fields available to be updated are 'target\_url', 'name', 'event\_type', 'payload', 'http\_headers', 'archived\_date', 'is\_archived'. | ### UpdateWebhookResponse The response of a call to `WebhookService_UpdateWebhook`. To archive a webhook, specify `archived_date` in the `update mask` as well as a non-null value for `archived_date` in the `webhook` object. To unarchive a webhook, specify `archived_date` in the `update mask` and a `null` value for `archived_date` in the `webhook` object. | Field | Type | Label | Description | | :------ | :------------------ | :---- | :---------- | | webhook | [Webhook](#webhook) | | | ### Webhook | Field | Type | Label | Description | | :--------------------- | :-------------------------------------- | :------- | :---------- | | webhook\_id | string | | | | organization\_id | string | | | | target\_url | string | | | | name | string | | | | event\_type | [WebhookEventType](#webhookeventtype) | | | | payload | string | optional | | | created\_date | google.protobuf.Timestamp | | | | modified\_date | google.protobuf.Timestamp | | | | archived\_date | google.protobuf.Timestamp | optional | | | created\_by\_user\_id | string | | | | modified\_by\_user\_id | string | | | | http\_headers | [WebhookHttpHeader](#webhookhttpheader) | repeated | | | is\_archived | bool | | | ### WebhookHttpHeader | Field | Type | Label | Description | | :---- | :----- | :---- | :---------- | | name | string | | | | value | string | | | ### WebhookLog | Field | Type | Label | Description | | :--------------------- | :------------------------------------ | :------- | :---------- | | webhook\_log\_id | string | | | | webhook\_id | string | | | | event\_id | string | | | | organization\_id | string | | | | status | [WebhookLogStatus](#webhooklogstatus) | | | | payload | string | optional | | | retry\_attempt\_number | uint32 | | | | error\_reason | string | optional | | | sent\_date | google.protobuf.Timestamp | | | | created\_date | google.protobuf.Timestamp | | | | modified\_date | google.protobuf.Timestamp | | | | created\_by\_user\_id | string | | | | modified\_by\_user\_id | string | | | ### WebhookSignatureKey | Field | Type | Label | Description | | :--------------------- | :------------------------ | :---- | :---------- | | signature\_key | string | | | | active | bool | | | | created\_date | google.protobuf.Timestamp | | | | modified\_date | google.protobuf.Timestamp | | | | created\_by\_user\_id | string | | | | modified\_by\_user\_id | string | | | ## Enums *Allowed constant values used in message fields.* ### WebhookEventType | Name | Number | Description | | :------------------------------------ | :----- | :---------- | | WEBHOOK\_EVENT\_TYPE\_UNSPECIFIED | 0 | | | WEBHOOK\_EVENT\_TYPE\_RULE\_VIOLATION | 1 | | ### WebhookLogStatus | Name | Number | Description | | :-------------------------------- | :----- | :---------- | | WEBHOOK\_LOG\_STATUS\_UNSPECIFIED | 0 | | | WEBHOOK\_LOG\_STATUS\_SENT | 1 | | | WEBHOOK\_LOG\_STATUS\_FAILED | 2 | | | WEBHOOK\_LOG\_STATUS\_RETRYING | 3 | |