Overview

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

Webhook authentication

Webhooks offer three authentication methods: API key, basic, and bearer token. Always use these authentication methods over HTTPS (TLS). For webhooks without authentication, simply exclude the authentication field from the request.

At Ironclad, it is possible to create and retrieve webhooks in the UI and through the API. To learn more about interacting with webhooks through the API visit the tutorial here.

Note: GET /webhooks redacts Authorization headers.

Reference for adding Authorization in User Interface

In the Ironclad UI go to Company Settings -> API -> Webhooks -> "Create a Webhook"

API key authentication

API POST Webhook Example

 POST /webhooks: Example request body

{  
    "events": [  
        "workflow_attribute_updated" //sample event 
    ],  
    "targetURL": "[WEBHOOK_TARGET_URL]",
    "headers": {
        "Authorization": "[WEBHOOK_API_AUTH_TOKEN]"
    }  
}

Webhook UI Example

Basic authentication

In order to use Basic authentication with our webhook authentication you need to have an encoded base 64 value of your credentials. We will refer to these as [WEBHOOK_BASIC_AUTH_BASE_64_ENCODED]

Please follow the steps here to generate an encoded basic auth.

API POST Webhook Example

{  
    "events": [  
        "workflow_attribute_updated" //sample event 
    ],  
    "targetURL": "[WEBHOOK_TARGET_URL]",
    "headers": {
       "Authorization": "Basic [WEBHOOK_BASIC_AUTH_BASE_64_ENCODED]"
    }  
}

Webhook UI Example

Bearer authentication

API POST Webhook Example

{  
    "events": [  
        "workflow_attribute_updated" //sample event 
    ],  
    "targetURL": "[WEBHOOK_TARGET_URL]",
    "headers": {
        "Authorization": "Bearer [WEBHOOK_BEARER_TOKEN]"
    }  
}

Webhook UI Example

Troubleshooting Errors

Once a webhook is configured it should appear in the main webhooks page. You can troubleshoot configuration and authentication issues in the Company Settings -> Errors page. More information is available here.