envless.webhooks.create()

create(body: WebhookCreate, options?: RequestScope): Promise<CreatedWebhookResource>

Registers an HTTPS receiver and subscribes it to a set of events. The endpoint is created with enabled set to true, so any matching event emitted after this call is queued for it straight away. The delivery worker drains the queue on a 5 second tick, so the first request usually lands a moment after this promise settles.

This response is the only place the API hands you the full secret. Every read gives you secretLastFour instead, so persist the secret before you do anything else. If you lose it you have two ways back: reveal it in the dashboard, which needs the webhooks:secret_read permission plus a step up verification, or call rotateSecret from here. Rotation is immediate and there is no overlap window, because each delivery is signed at send time from the endpoint's current secret, so queued deliveries and retries switch to the new secret too. The secret is formatted ev_whsec_ followed by base64url of 24 random bytes, and the HMAC key is the full string including that prefix: do not strip it, and if a verification library wants a base64 secret pass base64(utf8(secret)).

url is validated hard. It must be https, at most 2048 characters, free of embedded credentials, and pointed at a publicly routable host, which rules out loopback, private and carrier grade NAT ranges, link local and unique local IPv6, localhost, cloud metadata hosts and anything ending .internal, .local, .localdomain or .home.arpa. The host is checked again at delivery time: it is resolved and the attempt fails if any resolved address is private. Redirects are never followed, so a 3xx from your receiver is recorded as a failed attempt: register the final URL. eventTypes must be non empty and drawn from listEventTypes, and a 400 request.body_invalid names each offending value.

Example#

const created = await envless.webhooks.create({
    name: 'production sync',
    url: 'https://hooks.example.com/envless',
    eventTypes: ['variable.created', 'variable.updated']
})

console.log(created.secret)
console.log(created.id, created.secretLastFour)

Parameters#

Returns#

CreatedWebhookResource, a WebhookResource plus the plaintext secret. Alongside it you get id, name, url, description, eventTypes, enabled, secretLastFour, lastSuccessAt, lastFailureAt, createdAt and updatedAt.

Worth knowing#

Required scopes#

webhooks:write

Underlying endpoint#

In Python#

In Ruby#

In PHP#