API reference

Webhooks

API referencehttps://api.contit.cloud

Webhooks

Endpoints for managing outbound webhooks: CRUD, enable/disable, signing-secret rotation, synchronous test ping, delivery log inspection and retry, and sample event generation. On create both `id` and `secret` are generated server-side and returned in the PUT response — capture the secret then, as it is the same value used to sign every subsequent delivery. Every delivery is signed with an HMAC-SHA256 of `{timestamp}.{payload}` using the webhook secret; receivers should verify the `Contit-Signature: t={timestamp},s={hex}` header. Test pings additionally carry `Contit-Test: true`.

GET /webhooks

Retrieve all webhooks

Retrieves all webhooks configured for the current workspace.

Requires the ReadAccess policy

Responses

200Success
(array)WebhookModel[]Array of configured webhooks
403Forbidden
404Not Found — workspace does not exist

Code examples

curl -X GET "https://api.contit.cloud/webhooks" \
  -H "X-Api-Key: YOUR_API_KEY"
Example request
GET /webhooks
Example response 200
[
  {
    "id": "wh_a1b2c3d4",
    "endpoint": "https://example.com/hooks/contit",
    "secret": "wh_d4f6e9c2a1b8...",
    "eventTypes": {
      "article": [0, 1, 2]
    },
    "useCustomPayload": false,
    "customPayload": null,
    "description": "Production article sync",
    "errorEmailTo": "[email protected]",
    "enabled": true
  }
]
Try it Live
GET /webhooks/{id}

Retrieve webhook by ID

Retrieves a single webhook by its ID.

Requires the ReadAccess policy

Path parameters

NameTypeRequiredDescription
idstringWebhook ID

Responses

200Success
(object)WebhookModelThe webhook configuration
403Forbidden
404Not Found — webhook or workspace does not exist

Code examples

curl -X GET "https://api.contit.cloud/webhooks/{id}" \
  -H "X-Api-Key: YOUR_API_KEY"
Example request
GET /webhooks/wh_a1b2c3d4
Example response 200
{
  "id": "wh_a1b2c3d4",
  "endpoint": "https://example.com/hooks/contit",
  "secret": "wh_d4f6e9c2a1b8...",
  "eventTypes": {
    "article": [0, 1, 2]
  },
  "useCustomPayload": false,
  "customPayload": null,
  "description": "Production article sync",
  "errorEmailTo": "[email protected]",
  "enabled": true
}
Try it Live
PUT /webhooks

Create or update webhook

Creates a new webhook or updates an existing one (matched by `id`). The `endpoint` field is required. On **create**, both `id` and `secret` are generated automatically by the API (the secret has the form `wh_` + 32 random chars) and returned in the response — read it from the response body immediately because the same value is reused for HMAC signing on every delivery. Passing a non-empty `secret` in the body overrides the autogenerated one (useful only if you want to import an existing secret). On **update**, omitting `secret` (or sending an empty value) preserves the current one; pass an explicit value to replace it, or use `POST /webhooks/{id}/rotate-secret` to regenerate it server-side. The `eventTypes` map keys are content-type keys and values are arrays of `WebhookEventType` enum values: `0` Published, `1` Unpublished, `2` Deleted, `3` PublishedCreated, `4` PublishedUpdated.

Requires the WriteAccess policy

Request body application/json

PropertyTypeRequiredDescription
id string — Webhook ID. Omit (or empty) to create a new one.
endpoint string Absolute HTTPS URL the webhook will POST to
secret string — Signing secret used to compute the HMAC-SHA256 signature. Auto-generated on create if omitted (returned in the response). On update, omit to preserve the existing one.
eventTypes object — Map of `contentTypeKey` -> array of WebhookEventType values that trigger this webhook
useCustomPayload boolean — If true, the delivery body is built from `customPayload` instead of the default content envelope
customPayload object — JSON template used when `useCustomPayload` is true
description string — Free-text description shown in the admin UI
errorEmailTo string — Comma-separated list of email addresses notified on repeated delivery failures
enabled boolean — Whether the webhook is active. Disabled webhooks are configured but do not fire.

Responses

200Success — webhook created or updated
(object)WebhookModelThe persisted webhook configuration
400Bad Request — missing body or missing `endpoint`
403Forbidden
404Not Found — workspace does not exist

Code examples

curl -X PUT "https://api.contit.cloud/webhooks" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "id_value",
  "endpoint": "endpoint_value",
  "secret": "secret_value",
  "eventTypes": "eventTypes_value",
  "useCustomPayload": true,
  "customPayload": "customPayload_value",
  "description": "description_value",
  "errorEmailTo": "errorEmailTo_value",
  "enabled": true
}'
Example request
{
  "endpoint": "https://example.com/hooks/contit",
  "description": "Production article sync",
  "errorEmailTo": "[email protected]",
  "enabled": true,
  "eventTypes": {
    "article": [0, 1, 2]
  },
  "useCustomPayload": false
}
Example response 200
{
  "id": "wh_a1b2c3d4",
  "endpoint": "https://example.com/hooks/contit",
  "secret": "wh_d4f6e9c2a1b8...",
  "eventTypes": {
    "article": [0, 1, 2]
  },
  "useCustomPayload": false,
  "customPayload": null,
  "description": "Production article sync",
  "errorEmailTo": "[email protected]",
  "enabled": true
}
Try it Live
DELETE /webhooks/{id}

Delete webhook

Deletes a webhook by its ID. Existing delivery log entries are retained.

Requires the WriteAccess policy

Path parameters

NameTypeRequiredDescription
idstringWebhook ID

Responses

200Success — webhook deleted
403Forbidden
404Not Found — webhook or workspace does not exist

Code examples

curl -X DELETE "https://api.contit.cloud/webhooks/{id}" \
  -H "X-Api-Key: YOUR_API_KEY"
Example request
DELETE /webhooks/wh_a1b2c3d4
Try it Live
POST /webhooks/{id}/enable

Enable webhook

Sets `enabled = true` on the webhook so that future matching events will be delivered.

Requires the WriteAccess policy

Path parameters

NameTypeRequiredDescription
idstringWebhook ID

Responses

200Success — returns the updated webhook
(object)WebhookModelThe updated webhook configuration
403Forbidden
404Not Found

Code examples

curl -X POST "https://api.contit.cloud/webhooks/{id}/enable" \
  -H "X-Api-Key: YOUR_API_KEY"
Example request
POST /webhooks/wh_a1b2c3d4/enable
Example response 200
{
  "id": "wh_a1b2c3d4",
  "endpoint": "https://example.com/hooks/contit",
  "enabled": true
}
Try it Live
POST /webhooks/{id}/disable

Disable webhook

Sets `enabled = false`. The webhook configuration is preserved but no deliveries are queued until it is enabled again.

Requires the WriteAccess policy

Path parameters

NameTypeRequiredDescription
idstringWebhook ID

Responses

200Success — returns the updated webhook
(object)WebhookModelThe updated webhook configuration
403Forbidden
404Not Found

Code examples

curl -X POST "https://api.contit.cloud/webhooks/{id}/disable" \
  -H "X-Api-Key: YOUR_API_KEY"
Example request
POST /webhooks/wh_a1b2c3d4/disable
Example response 200
{
  "id": "wh_a1b2c3d4",
  "endpoint": "https://example.com/hooks/contit",
  "enabled": false
}
Try it Live
POST /webhooks/{id}/rotate-secret

Rotate webhook secret

Regenerates the signing secret of the webhook and returns the new value. The previous secret is invalidated immediately — update the receiver's verification logic before invoking this in production.

Requires the WriteAccess policy

Path parameters

NameTypeRequiredDescription
idstringWebhook ID

Responses

200Success — returns the webhook with the new secret
(object)WebhookModelThe webhook with the new `secret` value
403Forbidden
404Not Found

Code examples

curl -X POST "https://api.contit.cloud/webhooks/{id}/rotate-secret" \
  -H "X-Api-Key: YOUR_API_KEY"
Example request
POST /webhooks/wh_a1b2c3d4/rotate-secret
Example response 200
{
  "id": "wh_a1b2c3d4",
  "endpoint": "https://example.com/hooks/contit",
  "secret": "wh_NEWa7f3e1d2c9b6...",
  "enabled": true
}
Try it Live
POST /webhooks/{id}/test

Test webhook endpoint

Sends a synchronous HTTP POST to the configured endpoint with a small signed test payload (`eventType: "webhook.test"`). Adds `Contit-Test: true` and the standard `Contit-Signature` header. Returns the response status, body (truncated to 2000 chars) and duration. Times out after 10 seconds. Does **not** persist a delivery record in the event log.

Requires the WriteAccess policy

Path parameters

NameTypeRequiredDescription
idstringWebhook ID

Responses

200Test completed (success or failure) — the result is in the body
isSuccessStatusCodebooleanTrue if the endpoint returned a 2xx status
statusCodeintegerHTTP status code returned by the endpoint (0 if the request never reached the server, e.g. DNS error or timeout)
messagestringResponse body (truncated to 2000 chars) or client-side error message
durationMsintegerWall-clock duration of the request in milliseconds
400Bad Request — endpoint is not configured
403Forbidden
404Not Found

Code examples

curl -X POST "https://api.contit.cloud/webhooks/{id}/test" \
  -H "X-Api-Key: YOUR_API_KEY"
Example request
POST /webhooks/wh_a1b2c3d4/test
Example response 200
{
  "isSuccessStatusCode": true,
  "statusCode": 200,
  "message": "{\"ok\":true}",
  "durationMs": 184
}
Try it Live
GET /webhooks/{id}/events

Retrieve webhook delivery log

Returns the delivery log of a webhook, paginated and ordered newest-first. Supports optional filters: `status` (process status), `eventType`, `contentType`, `from`/`to` (insert date range, ISO-8601). `pageSize` is capped at 100.

Requires the ReadAccess policy

Path parameters

NameTypeRequiredDescription
idstringWebhook ID

Query parameters

NameTypeRequiredDescription
pageinteger—1-based page number (default 1)
pageSizeinteger—Items per page (default 20, max 100)
statusWebhookProcessStatus—Filter by process status: -1 Error, 0 Waiting, 1 Processing, 2 Sent
eventTypeWebhookEventType—Filter by event type: 0 Published, 1 Unpublished, 2 Deleted, 3 PublishedCreated, 4 PublishedUpdated
contentTypestring—Filter by content-type key
fromdatetime—Lower bound on insert date (ISO-8601, inclusive)
todatetime—Upper bound on insert date (ISO-8601, inclusive)

Responses

200Success — paginated delivery list
itemsWebhookEventLogModel[]Delivery entries on the current page
pageintegerCurrent page (1-based)
pageSizeintegerItems per page
totalintegerTotal matching deliveries across all pages
400Bad Request
403Forbidden
404Not Found

Code examples

curl -X GET "https://api.contit.cloud/webhooks/{id}/events" \
  -H "X-Api-Key: YOUR_API_KEY"
Example request
GET /webhooks/wh_a1b2c3d4/events?page=1&pageSize=20&status=-1
Example response 200
{
  "items": [
    {
      "id": "evt_9b8c7d6e5f4a",
      "webhookId": "wh_a1b2c3d4",
      "dateInsert": "2026-05-15T14:02:11Z",
      "lastUpdate": "2026-05-15T14:02:13Z",
      "eventType": 0,
      "contentId": "c_d4f6e9c2",
      "contentType": "article",
      "fields": { "title": "Hello world" },
      "translations": { "it": "Ciao mondo" },
      "customPayload": null,
      "processStatus": -1,
      "responseStatusCode": 502,
      "isResponseSuccessStatusCode": false,
      "responseMessage": "Bad Gateway"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}
Try it Live
GET /webhooks/{id}/events/{eventId}

Retrieve webhook delivery

Retrieves a single webhook delivery by its ID. Returns 404 if the event does not exist or does not belong to the given webhook.

Requires the ReadAccess policy

Path parameters

NameTypeRequiredDescription
idstringWebhook ID
eventIdstringDelivery ID

Responses

200Success
(object)WebhookEventLogModelThe delivery record (same shape as items in the events list)
403Forbidden
404Not Found — delivery or webhook does not exist

Code examples

curl -X GET "https://api.contit.cloud/webhooks/{id}/events/{eventId}" \
  -H "X-Api-Key: YOUR_API_KEY"
Example request
GET /webhooks/wh_a1b2c3d4/events/evt_9b8c7d6e5f4a
Example response 200
{
  "id": "evt_9b8c7d6e5f4a",
  "webhookId": "wh_a1b2c3d4",
  "dateInsert": "2026-05-15T14:02:11Z",
  "lastUpdate": "2026-05-15T14:02:13Z",
  "eventType": 0,
  "contentId": "c_d4f6e9c2",
  "contentType": "article",
  "fields": { "title": "Hello world" },
  "translations": { "it": "Ciao mondo" },
  "customPayload": null,
  "processStatus": 2,
  "responseStatusCode": 200,
  "isResponseSuccessStatusCode": true,
  "responseMessage": "OK"
}
Try it Live
POST /webhooks/{id}/events/{eventId}/retry

Retry webhook delivery

Re-enqueues an existing delivery for processing. A new delivery record is created in `Waiting` status using the original payload snapshot; the original entry is left untouched for audit.

Requires the WriteAccess policy

Path parameters

NameTypeRequiredDescription
idstringWebhook ID
eventIdstringDelivery ID to retry

Responses

200Success — retry enqueued
403Forbidden
404Not Found — delivery or webhook does not exist

Code examples

curl -X POST "https://api.contit.cloud/webhooks/{id}/events/{eventId}/retry" \
  -H "X-Api-Key: YOUR_API_KEY"
Example request
POST /webhooks/wh_a1b2c3d4/events/evt_9b8c7d6e5f4a/retry
Try it Live
POST /webhooks/{id}/generate-sample/{contentTypeId}

Generate sample webhook event

Generates a sample `Published` delivery for the given content type and enqueues it on the webhook. Useful to exercise the receiver end-to-end without touching real content. The sample payload contains a synthetic content ID and the content-type's field keys with `null` values.

Requires the WriteAccess policy

Path parameters

NameTypeRequiredDescription
idstringWebhook ID
contentTypeIdstringContent type ID to base the sample payload on

Responses

200Success — sample delivery enqueued
403Forbidden
404Not Found — webhook or content type does not exist

Code examples

curl -X POST "https://api.contit.cloud/webhooks/{id}/generate-sample/{contentTypeId}" \
  -H "X-Api-Key: YOUR_API_KEY"
Example request
POST /webhooks/wh_a1b2c3d4/generate-sample/article
Try it Live