Account, keys and webhooks ›

Create webhook

POST/v1/webhooks

Add a webhook. Answers with its signing secret, once.

RequestTypeScript

import { Agental } from "agental-sdk";
const agental = new Agental();
const webhook = await agental.createWebhook({
url: "https://example.com/hooks/agental",
});

Answer201 Created

{
"id": string,
"url": string,
"events": string[],
"description": string,
"createdAt": string,
"updatedAt": string,
"signingSecret": string,
"deliveries": [{
"id": string,
"event": string,
"status": string,
"httpStatus": integer | null,
"error": string | null,
"createdAt": string,
… 2 more
}],
}

Webhook stored.

Headers

Authorizationrequired

Bearer key

An API key that may make this call.

Body

`url`required string	Where events are POSTed. It has to start with http:// or https:// and be on the public internet. A private, loopback or reserved address is refused here. A name that leads to one is refused each time an event would be sent to it, and that delivery is recorded as failed. Redirects are not followed.
`events` array of string	What to send: sandbox.created, sandbox.started, sandbox.stopped, sandbox.archived, sandbox.error, sandbox.moved, sandbox.deleted, sandbox.auto_stop_set, sandbox.labels_changed, prompt.created, template.created, template.updated, template.secrets_changed (named, never with a value), template.labels_changed and template.deleted, or * for all of them, which is what is sent when this is left out. Each event has the same id in every webhook it is sent to, and a sandbox.* event in the log record a collector set with PUT /v1/telemetry is sent. e.g. `["sandbox.created","sandbox.error"]`
`description` string

Returns

201 Webhook stored. The signing secret is included once.

JSON8 fields

id

string

url

string

events

string[]

description

string

createdAt

string

updatedAt

string

signingSecret

string

Returned only on create and rotate.

deliveries

object[]8 fields

id

string

event

string

status

string

httpStatus

integernull

error

stringnull

createdAt

string

eventId

stringnull

The id of the event this was a try of: the id in what was sent.

An event that is not taken is tried again, eight times over about a day, under the same id.

attempt

integernull

Which try of that event this was, counted from 1.

Errors and other answers

400	Invalid request, or a url that is not one a webhook is sent to.
404	Not found.
409	`webhook_limit` the account has 20 webhooks, the most it may have.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← List webhooks Get webhook →