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 WebhookSecret
An optional field. When set, a hash signature is added to the request to validate that it was sent by env zero. 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
| Header | description |
|---|---|
| User-Agent | Equals to env-zero-webhook |
| x-env-zero-notification-target-id | The ID of the notification target to which the request was sent. |
| x-env-zero-event | The event type, e.g., com.env-zero.deploy.succeeded |
| x-env-zero-event-id | A globally unique ID that identifies the request |
| x-env-zero-signature | If a secret is set, contains the hash signature. More details in the ‘Validating webhook deliveries’ section below. |
Body
| Param | description |
|---|---|
| type | The event type, e.g., com.env-zero.deploy.succeeded |
| source | Should be equal to env-zero-webhooks |
| id | A globally unique ID that identifies the request |
| datacontenttype | Equals to application/json |
| data | Event data, JSON encoded. Schema is defined by the event type as specified in our API reference under the WEBHOOKS section |
Request example
Headers
| Header | value |
|---|---|
| User-Agent | env0-webhook |
| x-env0-notification-target-id | 727dbd33-38d3-4057-ab4d-19bc6d40a1d9 |
| x-env0-event | com.env0.webhook.test |
| x-env0-event-id | e6328df5-81d7-4dd8-851f-66c01f87b5c7 |
| x-env0-signature | 0b844da97d713d4965b66b72d0e9dc9fa8990e601acb8d7cdd33b560d41891d7 |
Body
JSON
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).Example Webhook Payload
json
Validating webhook deliveries
If a secret is set for the webhook, env zero will use it to create a hash signature that can be used to make sure that the request was sent by env zero. The signature is set in thex-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.Protecting against replay attacks
To mitigate replay attacks, where a bad actor intercepts webhook deliveries and re-sends the requests, use thex-env0-event-id header to ensure that each request is unique.