---
title: "Register a webhook endpoint, returning its signing secret once"
method: POST
path: "/v1/webhooks"
tags: ["webhooks"]
---

# Register a webhook endpoint, returning its signing secret once

`POST /v1/webhooks`

## Request

- Base URL: `https://api.indraft.io`
- URL: `https://api.indraft.io/v1/webhooks`
- Auth: HTTP bearer

The signing secret is in this response and nowhere else. Verify a delivery by recomputing the signature over the timestamp and the raw body. An address that is not https, or one on a private, loopback or cloud-metadata range, is refused here rather than at delivery time.

## Request body

- object
  - `url` string, required
  - `events` union[]
    - union
      - 'advance_opportunity' | 'configure_watch' | 'advance_custom_record' | 'archive' | 'restore' | 'archive_custom_record' | 'cancel_task' | 'update_task' | 'complete_task' | 'configure_custom_field' | 'configure_exchange_rate' | 'configure_object_type' | 'configure_pipeline' | 'configure_workspace' | 'set_standing_override_policy' | 'confirm' | 'create_opportunity' | 'create_task' | 'erase_subject' | 'link_contact_company' | 'merge_companies' | 'merge_contacts' | 'merge_object_records' | 'record_interaction' | 'revert_change' | 'unmerge' | 'update_opportunity' | 'upsert_company' | 'upsert_contact' | 'upsert_custom_record'
      - 'watch_fired'
  - `description` string

## Response `200`

Success

- object
  - `endpoint` object, required
    - `id` string, required
    - `url` string, required
    - `events` string[], required
    - `description` string, required
    - `createdAt` string, required
    - `disabledAt` string, required
  - `secret` string, required
  - `requestId` string, required

## Other responses

- `401`: No credential, or one that has been revoked.
- `402`: A product quota is spent, or the subscription is not active.
- `403`: Authenticated, and this capability is not held.
- `409`: A conflict the caller can resolve: a stale expectedVersion, an idempotency key reused for different input, an ambiguous or duplicate identity, or a merge that no longer applies.
- `413`: The body, or a single record inside it, exceeds its bound.
- `422`: The request does not satisfy the schema on this page.
- `429`: Infrastructure protection tripped. This is not a product quota.
- `500`: A defect on our side. The hint says so, and carries an incident id.
- `507`: The workspace is at its storage ceiling.

---

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