Webhooks allow our system to instantly notify your server whenever a specific event occurs, providing a secure and flexible way to create custom integrations with your env0 account. For example, you can use webhooks to send notifications to your preferred collaboration platform, update JIRA tickets, or log events in real-time.

Setup a webhook

Name

The name of the webhook notification target must be unique across the organization.

URL

The URL to which an HTTP request will be sent with data about the event. An HTTPS connection is required. You can easily experiment with webhooks without the need to set up a server by using services such as webhook.site.

Type

Must be set to Webhook

Secret

An optional field. When set, a hash signature is added to the request to validate that it was sent by env0. More details can be found in the 'Validating webhook deliveries' section below.

When using a secret, you should choose a random string with high entropy and store it in a secure location that you can later access to validate the request.

Request structure

Headers

Body

Request example

Headers

Body

{
  "type": "com.env0.webhook.test",
  "source": "https://env0.com",
  "id": "b6cf1180-7bbb-4640-9a0b-98e012756b55",
  "time": "2024-05-15T09:22:12.315Z",
  "datacontenttype": "application/json",
  "data": {
    "endpoint": {
      "id": "727dbd33-38d3-4057-ab4d-19bc6d40a1d9",
      "value": "<webhook url>",
      "type": "Webhook",
      "organizationId": "bd12a04a-b051-4f51-9a8a-8a32ac198802"
    }
  }
}

Testing a webhook

You can test your webhook by clicking 'Test endpoint':

Then click 'Send test event' to send a test event and examine the request and response (or error details).

Validating webhook deliveries

If a secret is set for the webhook, env0 will use it to create a hash signature that can be used to make sure that the request was sent by env0. The signature is set in the x-env0-signature header.

In your code that handles the requests, you should calculate the hash signature using the secret and the request body. Then, make sure that it equals the signature in the request x-env0-signature header.

Notes

• The signature is computed based on the webhook secret and the request body using HMAC hex digset.
• When calculating the signature on your side, decode the body as UTF-8.
• To mitigate certain timing attacks, it is highly recommended not to use plain == operator when comparing the signature in the request with the one you calculated. Instead, use methods like secure_compare or crypto.timingSafeEqual, which perform a "constant time" string comparison

Verify your implementation

You can use the following secret and payload to make sure that your implementation is correct:

secret: "Secret example"
payload: "Hello, World!"
A correct implementation should generate the following signature:
0b844da97d713d4965b66b72d0e9dc9fa8990e601acb8d7cdd33b560d41891d7

Examples

Here's what signature validation might look like in various programming languages.

import * as crypto from "crypto";

const WEBHOOK_SECRET: string = process.env.WEBHOOK_SECRET;

const verify_signature = (req: Request) => {
  const signature = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest("hex");
  let trusted = Buffer.from(`sha256=${signature}`, 'ascii');
  let untrusted =  Buffer.from(req.headers.get("x-hub-signature-256"), 'ascii');
  return crypto.timingSafeEqual(trusted, untrusted);
};

const handleWebhook = (req: Request, res: Response) => {
  if (!verify_signature(req)) {
    res.status(401).send("Unauthorized");
    return;
  }
  // The rest of your logic here
};

let encoder = new TextEncoder();

async function verifySignature(secret, header, payload) {
    let parts = header.split("=");
    let sigHex = parts[1];

    let algorithm = { name: "HMAC", hash: { name: 'SHA-256' } };

    let keyBytes = encoder.encode(secret);
    let extractable = false;
    let key = await crypto.subtle.importKey(
        "raw",
        keyBytes,
        algorithm,
        extractable,
        [ "sign", "verify" ],
    );

    let sigBytes = hexToBytes(sigHex);
    let dataBytes = encoder.encode(payload);
    let equal = await crypto.subtle.verify(
        algorithm.name,
        key,
        sigBytes,
        dataBytes,
    );

    return equal;
}

function hexToBytes(hex) {
    let len = hex.length / 2;
    let bytes = new Uint8Array(len);

    let index = 0;
    for (let i = 0; i < hex.length; i += 2) {
        let c = hex.slice(i, i + 2);
        let b = parseInt(c, 16);
        bytes[index] = b;
        index += 1;
    }

    return bytes;
}

import hashlib
import hmac
def verify_signature(payload_body, secret_token, signature_header):
    """Verify that the payload was sent from GitHub by validating SHA256.

    Raise and return 403 if not authorized.

    Args:
        payload_body: original request body to verify (request.body())
        secret_token: GitHub app webhook token (WEBHOOK_SECRET)
        signature_header: header received from GitHub (x-hub-signature-256)
    """
    if not signature_header:
        raise HTTPException(status_code=403, detail="x-hub-signature-256 header is missing!")
    hash_object = hmac.new(secret_token.encode('utf-8'), msg=payload_body, digestmod=hashlib.sha256)
    expected_signature = "sha256=" + hash_object.hexdigest()
    if not hmac.compare_digest(expected_signature, signature_header):
        raise HTTPException(status_code=403, detail="Request signatures didn't match!")

Protecting against replay attacks

To mitigate replay attacks, where a bad actor intercepts webhook deliveries and re-sends the requests, use the x-env0-event-id header to ensure that each request is unique.

Allow env0's IP addresses

env0 will use the IP addresses listed here when sending a request to the webhook URL. You can add these to your server IP allow list to block spoofed requests.

10-seconds response timeout

Your server should respond within 10 seconds with a 2XX response. If it takes longer, the delivery fails.

No retries for failed requests

If a request to the webhook URL fails, env0 will not retry to send the event.