Create a webhook subscription

POST
/hooks/subscriptions

Creates a webhook subscription for one target URL and returns its signing secret. Created unconfirmed, so it receives nothing until you call the confirm endpoint and Terac's ping to target_url returns 2xx. A URL that already has a subscription returns 409; patch that one's event_types instead.

Authorization

apiKey
Authorization<token>

API key as Bearer token: Authorization: Bearer

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://terac.com/api/external/v2/hooks/subscriptions" \  -H "Content-Type: application/json" \  -d '{    "target_url": "http://example.com",    "event_types": [      "submission.status.change"    ]  }'
{
  "id": "string",
  "target_url": "string",
  "event_types": [
    "submission.status.change"
  ],
  "is_enabled": true,
  "confirmed_at": "string",
  "disabled_at": "string",
  "disabled_reason": "string",
  "created_at": "string",
  "updated_at": "string",
  "secret": "string"
}
{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key required. Include Authorization: Bearer <key> header."
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This account is not permitted to use the API."
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 61 seconds."
  }
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}

List webhook subscriptions GET

Lists every webhook subscription in your organization, one per target URL, with its event types and whether it is confirmed and enabled. Not paginated. Signing secrets are left out; read one from `GET /hooks/subscriptions/{subscriptionId}/secret`.

Get a webhook subscription GET

Returns one webhook subscription: its target URL, event types, and whether it is confirmed and enabled. disabled_reason is set when Terac disabled it after sustained delivery failure; patch is_enabled to true to turn it back on. The signing secret is left out.