webhook.proto

syntax = "proto3";

package hiber.webhook;

import "base.proto";
import "tag.proto";

option java_multiple_files = false;
option java_package = "global.hiber.api.grpc.webhook";
option java_outer_classname = "WebhookApi";
option go_package = ".;hiber";

service WebhookService {
    rpc List (ListWebhooksRequest) returns (ListWebhooksRequest.Response);
    rpc History (WebhookHistoryRequest) returns (WebhookHistoryRequest.Response);
    rpc Create (CreateWebhookRequest) returns (Webhook);
    rpc Enable (EnableWebhookRequest) returns (Webhook);
    rpc Disable (DisableWebhookRequest) returns (Webhook);
    rpc UpdateFilter (UpdateWebhookFilterRequest) returns (Webhook);
    rpc Update (UpdateWebhookRequest) returns (Webhook);
    rpc UpdateWebhooks (UpdateWebhooksRequest) returns (UpdateWebhooksRequest.Response);
    rpc UpdateTags (UpdateWebhookTagsRequest) returns (UpdateWebhookTagsRequest.Response);
    rpc Get (GetWebhookRequest) returns (Webhook);
    rpc Delete (DeleteWebhookRequest) returns (DeleteWebhookRequest.Response);
}

/* Webhook publisher that sends events to a webhook.
 *
 * When the webhook call fails, it enters cooldown, so as not to overload a failing server
 * or spend unnecessary time on an incorrectly configured webhook.
 * When the first call after the cooldown time has passed fails again, the cooldown is increased as follows:
 * 1m, 2m, 5m, 10m, 15m, 30m, 1h, 3h, 6h, 12h, 24h.
 *
 * To disable the cooldown, use EnableWebhookRequest to re-enable it.
 */
message Webhook {
    int64 id = 1;
    string organization = 2;
    string created_by = 10;
    string description = 3;
    WebhookData data = 4;
    WebhookFilters filters = 5;
    repeated hiber.tag.Tag tags = 6;

    Health health = 7;
    HealthConfig health_config = 9;

    /* The time the cooldown ends. */
    Timestamp in_cooldown_until = 8;

    enum ContentType {
        DEFAULT = 0;
        JSON = 1;
        PROTO = 2;
    }

    message WebhookData {
        string url = 1;

        /* Used to generate the HMAC-SHA256 header on every webhook call, which you can use to verify the message.
         * The HMAC-SHA256 header is calculated with the message body and this secret.
         * There are many examples of how to do this in different languages, for example:
         * https://github.com/danharper/hmac-examples
         */
        optional string secret = 2;

        /* The header that the hmac value is placed in. Defaults to X-Hub-Signature. */
        string hmac_header_name = 9;

        ContentType content_type = 3;
        bool disabled = 4;
        optional int64 certificate_id = 5;
        optional string certificate_name = 6;
        optional int64 ca_certificate_id = 7;
        optional string ca_certificate_name = 8;

        /* Custom headers to add to every call. */
        map<string, string> custom_headers = 10;
    }

    message WebhookFilters {
        optional Filter.Events event_types = 1;
        optional Filter.Modems modem_numbers = 2;
        optional Filter.Tags tags = 3;

        /* Filter events by health level caused. */
        repeated string health_levels = 4;
    }

    /* Health configuration for the webhook. Defines how the health is calculated. */
    message HealthConfig {
        reserved 1;

        /* Period to consider when determining health from warning events. Warning events cannot be resolved. */
        Duration health_warning_period = 2;

        /* Allowed percentage of failures.
         * If the failure percentage is higher, within the warning period, the health is switched to WARNING.
         */
        int32 health_warning_failure_percentage = 3;
    }
}

message WebhookSelection {
    optional string description = 1;
    optional string url = 2;
    optional Filter.Webhooks webhooks = 3;
    optional hiber.tag.TagSelection tags = 4;
    repeated Health health = 5;
    repeated int64 certificate_ids = 6;

    /* Search in the all available text, like description and url. */
    optional string search = 7;
}

message WebhookCall {
    Timestamp time = 1;
    string url = 2;
    map<string, string> headers = 3;
    bytes body_proto = 4;
    string body_json = 7;
    bool successful = 5;
    string error = 6;
}

message WebhookHistorySelection {
    optional bool only_failures = 2;
    optional TimeRange time_range = 3;
}

message ListWebhooksRequest {
    enum Sort {
        /* Sort by id. */
        DEFAULT = 0;

        /* Sort by id, high to low. */
        ID_DESC = 1;

        /* Sort by description. */
        DESCRIPTION = 2;

        /* Sort by description, z to a. */
        DESCRIPTION_DESC = 3;

        /* Sort by url. */
        URL = 4;

        /* Sort by url, z to a. */
        URL_DESC = 5;

        /* Sort unhealthy webhooks before health webhooks. */
        HEALTH = 6;
    }

    message Response {
        repeated Webhook webhooks = 1;
        ListWebhooksRequest request = 2;
        Pagination.Result pagination = 3;
    }

    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    optional string organization = 1;

    /* Select the webhooks to list. Optional, when omitted or empty everything is included. */
    optional WebhookSelection selection = 2;
    optional Pagination pagination = 3;
    repeated Sort sort = 4;
}

message WebhookHistoryRequest {
    message Response {
        repeated WebhookCall calls = 1;
        WebhookHistoryRequest request = 2;
        Pagination.Result pagination = 3;
    }

    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    optional string organization = 1;
    int64 webhook_id = 2;
    optional WebhookHistorySelection selection = 3;
    optional Pagination pagination = 4;
}

message CreateWebhookRequest {
    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    optional string organization = 1;
    string description = 2;
    Webhook.WebhookData data = 3;
    optional Webhook.WebhookFilters filters = 4;

    /* Filter events by health level caused. */
    repeated string health_levels = 7;

    repeated int64 tags = 5;

    /* Optionally, a client certificate can be used for the webhook call.
     * See the CertificateService for certificate management options.
     */
    optional int64 certificate_id = 6;
}

message GetWebhookRequest {
    int64 id = 1;
    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    string organization = 2;
    reserved 3;
}

message EnableWebhookRequest {
    int64 id = 1;
    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    string organization = 2;
    reserved 3;
}

message DisableWebhookRequest {
    int64 id = 1;
    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    string organization = 2;
    reserved 3;
}

message UpdateWebhookFilterRequest {
    int64 id = 1;
    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    string organization = 2;
    reserved 6;
    optional Filter.Events.Update deprecated_event_filter = 7 [deprecated = true];
    optional Filter.Events event_filter = 12;
    optional Filter.Modems.Update deprecated_modem_filter = 8 [deprecated = true];
    optional Filter.Modems modem_filter = 13;
    optional Filter.Tags.Update deprecated_tag_filter = 9 [deprecated = true];
    optional Filter.Tags tag_filter = 14;

    /* Add health levels to the health levels filter. */
    repeated string add_health_levels_to_filter = 10;

    /* Remove health levels from the health levels filter. */
    repeated string remove_health_levels_from_filter = 11;
}

message UpdateWebhookRequest {
    message UpdateWebhook {
        message UpdateEvents {
            option deprecated = true;

            bool updated = 1;
            Filter.Events value = 2;
        }
        message UpdateModems {
            option deprecated = true;

            bool updated = 1;
            Filter.Modems value = 2;
        }
        message UpdateTags {
            option deprecated = true;

            bool updated = 1;
            Filter.Tags value = 2;
        }

        string url = 1;

        optional UpdateClearableString deprecated_secret = 2 [deprecated = true];
        optional string secret = 22;

        optional Webhook.ContentType content_type = 3;

        optional UpdateClearableString deprecated_description = 4 [deprecated = true];
        optional string description = 23;

        optional Filter.Events.Update deprecated_event_filter = 10 [deprecated = true];
        optional Filter.Events event_filter = 24;
        optional Filter.Modems.Update deprecated_modem_filter = 11 [deprecated = true];
        optional Filter.Modems modem_filter = 25;
        optional Filter.Tags.Update deprecated_tag_filter = 12 [deprecated = true];
        optional Filter.Tags tag_filter = 26;

        /* Add health levels to the health levels filter. */
        repeated string add_health_levels = 16;

        /* Remove health levels from the health levels filter. */
        repeated string remove_health_levels = 17;

        optional UpdateBoolean deprecated_active = 8 [deprecated = true];
        optional bool active = 27;

        /* A value of 0 removes the certificate */
        optional UpdateOptionalId deprecated_certificate_id = 9 [deprecated = true];
        optional int64 certificate_id = 28;

        reserved 13;

        /* Period to consider when determining health from warning events. Warning events cannot be resolved.
         * Set this to 0 to disable warnings based on failure percentage.
         */
        optional Duration health_warning_period = 14;

        /* Allowed percentage of call failures.
         * If the failure percentage is higher, within the warning period, the health is switched to WARNING.
         */
        optional uint32 health_warning_failure_percentage = 29;
        optional UpdateZeroableInt deprecated_health_warning_failure_percentage = 15 [deprecated = true];

        /* Update the custom hmac header, or clear to reset to default. */
        optional string update_hmac_header_name = 30;
        optional UpdateClearableString deprecated_update_hmac_header_name = 18 [deprecated = true];

        /* Custom headers to add to every call. */
        map<string, string> add_custom_headers = 19;

        /* Remove previously configured custom headers. */
        repeated string remove_custom_headers = 20;

        /* Replace the custom headers to add to every call. If set, remove_custom_headers is ignored. */
        map<string, string> replace_custom_headers = 21;
    }

    int64 id = 1;
    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    string organization = 2;
    UpdateWebhook update = 3;
    reserved 4;
}

message UpdateWebhooksRequest {
    message Update {
        int64 id = 1;
        UpdateWebhookRequest.UpdateWebhook update = 2;
    }

    message Response {
        repeated Webhook webhooks = 1;
        UpdateWebhooksRequest request = 2;
    }

    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    optional string organization = 1;
    repeated Update webhook_updates = 2;
}

message UpdateWebhookTagsRequest {
    message Response {
        repeated Webhook webhooks = 1;
    }

    optional string organization = 1;
    repeated int64 webhook_ids = 2;
    hiber.tag.UpdateTagsForItem update = 3;
    reserved 4;
}

message DeleteWebhookRequest {
    message Response {
    }

    int64 id = 1;
    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    string organization = 2;
}