Webhook security and authentication

Webhooks use authentication to securely integrate with their destination systems and signing secrets to verify the integrity of their requests. This article describes the supported types of authentication and how to configure authentication.

For reference information, see Webhooks in the API documentation.

Webhook authentication

Webhooks support three types of authentication: API key, basic, and bearer token. All types of authentication should only be used over HTTPS (TLS).

Although not recommended, it's also possible to create a webhook without authentication. To do this, omit the authentication property from the request.

API key authentication

API key authentication uses a name and key value in a header. To create a webhook with API key authentication, use the authentication property to specify the name and value in your request to create the webhook. For more information about character limits, see Creating a webhook with custom headers.

Example

{
    "authentication": {
        "type": "api_key",
        "data": {
            "name": "HEADER_NAME",
            "value": "VALUE"
        },
        "add_position": "header"
    }
}

Basic authentication

Basic authentication uses a username and password. To create a webhook with basic authentication, use the authentication property to specify the username and password in your request to create the webhook.

Example

{
    "authentication":{
        "type":"basic_auth",
        "data":{
            "username":"USERNAME",
            "password":"PASSWORD"
        },
        "add_position":"header"
    }
}

Bearer authentication

Bearer authentication is an HTTP authentication scheme commonly referred to as token authentication. Bearer tokens are opaque strings, and they're the predominant type of access token used with OAuth 2.0.

To create a webhook with bearer token authentication, use the authentication property to specify the token in your request to create the webhook.

Example

{
    "authentication":{
        "type":"bearer_token",
        "data":{
            "token":"TOKEN"
        },
        "add_position":"header"
    }
}

Webhook signing secrets

You have the option to sign requests from webhooks so the destination system can verify their integrity. To do this, create a signing secret for the webhook and then incorporate the secret into the destination system's code to validate the requests' signature. For more information, see Verifying webhook authenticity.