Skip to main content
A webhook sends an HTTP POST with a JSON body to your endpoint each time one of the events you pick happens in your company, such as a deployment of an application finishing. Use webhooks to post deploy notifications to chat, start tests after a deployment, or keep another system in sync without polling the API. A company can have up to 10 webhooks, under Tools > Webhooks.

How webhooks work

Before you begin

  • You need the Company owner or Company admin role. See users and roles.
  • The company needs a valid payment method. Without one, the sheet shows Add a payment method to create a webhook.
  • Your endpoint must be a public http:// or https:// URL. Use https://, because the signing secret travels in a header. Endpoints that resolve to private, loopback or link-local addresses are rejected with The provided endpoint is not allowed.

Create a webhook

1

Open Webhooks

In the sidebar, under Tools, click Webhooks, then click Create webhook.
2

Enter the endpoint

In Endpoint, enter the URL that receives the events, for example https://hooks.example.com/sevalla. Optionally add a Description.
3

Pick the events

Under Allowed events, tick the events to send, or Select all.
4

Create the webhook

Click Create webhook.
The Create webhook sheet with the Endpoint and Description fields and the Allowed events checklist grouped by Applications, Databases and Static sitesThe Create webhook sheet with the Endpoint and Description fields and the Allowed events checklist grouped by Applications, Databases and Static sites
The webhook appears in the list with the status Active and starts sending events right away. To get its signing secret, click the webhook: on its Overview tab, under Details, Signing secret has buttons to show and copy it. Store the secret where your endpoint can read it, such as an environment variable. A company that already has 10 webhooks gets You can only create up to 10 webhooks per company.

Events

You can select the three database events, but Sevalla doesn’t send them yet. A webhook subscribed only to database events receives no deliveries.
Deployments of preview apps and pull request previews send deploy events too, with is_preview set to true.

Payload

Every request body has the same envelope. data depends on the event type.
string
ID of the webhook that sent the request.
string
ID of the event. The same on every retry, so use it to drop duplicates.
string
ID of this delivery attempt. A new one on every retry.
string
The event, such as APP_DEPLOY.
object
The event’s details.

Verify requests

The svl-signature header contains the webhook’s signing secret itself, not a hash of the body. To check that a request comes from Sevalla, compare the header with the secret you stored, in constant time, and reject the request with 401 when it doesn’t match. While a secret rollover is under way, accept both the old and the new secret.
For a complete receiver that forwards events to a chat channel, see the Discord webhook example, which you can deploy as a Sevalla application.

Retries

When a delivery fails, Sevalla retries it. Each retry is a new delivery with a new event_delivery_id and the same event_id. Retries stop as soon as one delivery succeeds. Sevalla retries an event only during the 4 days after it happened, so the 10th retry, about 2 days and 8 hours after the event, is the last one. If it fails too, the event isn’t sent again. Retries go to the endpoint the webhook had when the event happened, and they carry the current signing secret. Respond with a 2xx as soon as you’ve checked the signature, and do slow work afterwards, so a slow handler isn’t counted as a failure.

Check deliveries

Click a webhook to open it. Its Overview tab shows the Details and, under Analytics, the last 7 days in 2-hour intervals: Event deliveries (succeeded and failed) and Response time (average). The Webhooks list shows each webhook’s Error rate: the share of its deliveries in the last 7 days that failed. The Event deliveries tab lists every delivery, newest first. Filter by event ID with Filter by ID… or by Status, and click a delivery to see its Type, Status, Attempt date, Endpoint, Event ID, the Request payload, and the Response status code, time and body (up to 10,000 characters).
A webhook's Event deliveries tab with a failed delivery open, showing its details, request payload and responseA webhook's Event deliveries tab with a failed delivery open, showing its details, request payload and response
There’s no button to resend an event by hand: Sevalla retries failed events on its own.

Roll the secret

Rolling gives the webhook a new signing secret. The old secret can keep signing deliveries for up to 24 hours, so you can update your endpoint first.
1

Open the webhook

Under Tools, click Webhooks, then click the webhook. On the Overview tab, click Roll secret.
2

Choose how long the old secret signs

Under Expiration, pick Now, 1 hour, 2 hours, 4 hours, 8 hours, 16 hours or 24 hours (the default). Now switches to the new secret at once, so requests fail verification until your endpoint has it.
3

Roll

Click Roll secret.
Until the period ends, Signing secret shows the new secret with a Rolling over note that gives the time it’s activated, and the old secret below it. Deliveries keep carrying the old secret until that time, then the new one. Add the new secret to your endpoint (for example as SEVALLA_WEBHOOK_SECRET, with the old one as SEVALLA_WEBHOOK_SECRET_OLD) before the period ends, then remove the old one.

Update a webhook

On the webhook’s Overview tab, click Update, change the Endpoint, Description or Allowed events, then click Update webhook. Changes apply to the next event. Retries of earlier events still go to the endpoint the event was sent to first.

Disable or enable a webhook

1

Open the danger zone

On the webhook’s Overview tab, under Danger zone, click Disable webhook (or Enable webhook).
2

Confirm

Click Disable webhook (or Enable webhook) in the dialog.
The status changes to Disabled or Active. Events that happen while a webhook is disabled aren’t sent later. Retries of deliveries that failed before you disabled it continue.

Delete a webhook

Deleting a webhook deletes its event deliveries and analytics. You can’t undo this.
1

Open the danger zone

On the webhook’s Overview tab, under Danger zone, click Delete webhook.
2

Confirm

Type the webhook’s endpoint, then click Delete webhook.

API and CLI

The API’s roll operation takes expire_in_hours from 0 (the default) to 24. The API reference also describes the payload on Webhook events.