---
title: "Register a webhook endpoint"
method: POST
path: "/webhooks"
tags: ["webhooks"]
---

# Register a webhook endpoint

`POST /webhooks`

## Request

- Base URL: `https://api.gogoscreen.com/api/v1`
- URL: `https://api.gogoscreen.com/api/v1/webhooks`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Register an address to be POSTed to when work finishes, so an integration can stop polling. The signing secret is in the response and nowhere else. The URL is checked at registration AND again before every delivery — https outside development, no username or password, no fragment, no non-default port in production, and every address it resolves to must be public. The connection is then pinned to the address that was checked, and a redirect is refused rather than followed. At most 10 active endpoints per account.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `description` string: What this endpoint is for. Shown in the console and in the account's audit trail.
  - `events` string[], required: What to send. At least one; an unknown name is refused rather than ignored, because an endpoint subscribed to a typo would silently never fire.
  - `url` string, required: Where to POST. https, a public address, no credentials in the URL.

## Response `201`

Register a webhook endpoint

- object
  - `endpoint` object, required
    - `createdAt` string, date-time, required
    - `description` string, nullable, required
    - `disabledAt` string, date-time, nullable, required
    - `disabledReason` string, nullable, required: `owner` when you turned it off, `consecutive_failures` when we did.
    - `events` string[], required: The event types this endpoint asked for. Anything not on the list is not sent.
    - `failureStreak` number, required: Consecutive failed deliveries. Any success resets it; at 20 the endpoint is disabled automatically.
    - `id` string, required
    - `lastDeliveryAt` string, date-time, nullable, required
    - `status` 'active' | 'disabled', required
    - `updatedAt` string, date-time, required
    - `url` string, required: Where the signed POST goes. `https` outside development; the address is re-checked before every delivery.
  - `secret` string, required: THE SIGNING SECRET. This is the only time it is returned: it is stored encrypted and is never answered again. Verify every delivery with it — `Gogoscreen-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>." + raw body)>` — over the RAW request body, and reject a `t` more than five minutes from your clock.

## Other responses

- `400`: `validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `webhook_url_invalid` — That webhook URL is not one this API will post to. Use an https URL with no username, password or fragment. · `webhook_url_blocked` — That webhook URL resolves to an address this API will not post to. Point it at a public address. · `webhook_host_denied` — That webhook host is not allowed by this deployment.
- `401`: `unauthorized` — Authentication is required.
- `403`: `forbidden_scope` — This credential does not carry the scope this operation needs. · `email_unverified` — Confirm your email address to use this operation.
- `404`: `not_found` — No such resource.
- `409`: `idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `too_many_endpoints` — This account already has the maximum number of active webhook endpoints. Delete one to add another.
- `413`: `payload_too_large` — That request body is too large.
- `415`: `unsupported_media_type` — That content type is not supported.
- `429`: `rate_limited` — Too many requests. Try again shortly.
- `500`: `internal_error` — Something went wrong. Try again.

---

[API](https://skmtc.dev/gogoscreen/apis/gogoscreen-api.md) · [All operations](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/revisions/2fd812319d75?raw)