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.

Richiede la policy ReadAccess

Risposte

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

Esempi di codice

curl -X GET "https://api.contit.cloud/webhooks" \
  -H "X-Api-Key: YOUR_API_KEY"
Esempio di richiesta
GET /webhooks
Esempio di risposta 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
  }
]
Prova Live
GET /webhooks/{id}

Retrieve webhook by ID

Retrieves a single webhook by its ID.

Richiede la policy ReadAccess

Parametri del percorso

NomeTipoObbligatorioDescrizione
idstringWebhook ID

Risposte

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

Esempi di codice

curl -X GET "https://api.contit.cloud/webhooks/{id}" \
  -H "X-Api-Key: YOUR_API_KEY"
Esempio di richiesta
GET /webhooks/wh_a1b2c3d4
Esempio di risposta 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
}
Prova 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.

Richiede la policy WriteAccess

Corpo della richiesta application/json

ProprietàTipoObbligatorioDescrizione
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.

Risposte

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

Esempi di codice

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
}'
Esempio di richiesta
{
  "endpoint": "https://example.com/hooks/contit",
  "description": "Production article sync",
  "errorEmailTo": "[email protected]",
  "enabled": true,
  "eventTypes": {
    "article": [0, 1, 2]
  },
  "useCustomPayload": false
}
Esempio di risposta 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
}
Prova Live
DELETE /webhooks/{id}

Delete webhook

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

Richiede la policy WriteAccess

Parametri del percorso

NomeTipoObbligatorioDescrizione
idstringWebhook ID

Risposte

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

Esempi di codice

curl -X DELETE "https://api.contit.cloud/webhooks/{id}" \
  -H "X-Api-Key: YOUR_API_KEY"
Esempio di richiesta
DELETE /webhooks/wh_a1b2c3d4
Prova Live
POST /webhooks/{id}/enable

Enable webhook

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

Richiede la policy WriteAccess

Parametri del percorso

NomeTipoObbligatorioDescrizione
idstringWebhook ID

Risposte

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

Esempi di codice

curl -X POST "https://api.contit.cloud/webhooks/{id}/enable" \
  -H "X-Api-Key: YOUR_API_KEY"
Esempio di richiesta
POST /webhooks/wh_a1b2c3d4/enable
Esempio di risposta 200
{
  "id": "wh_a1b2c3d4",
  "endpoint": "https://example.com/hooks/contit",
  "enabled": true
}
Prova 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.

Richiede la policy WriteAccess

Parametri del percorso

NomeTipoObbligatorioDescrizione
idstringWebhook ID

Risposte

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

Esempi di codice

curl -X POST "https://api.contit.cloud/webhooks/{id}/disable" \
  -H "X-Api-Key: YOUR_API_KEY"
Esempio di richiesta
POST /webhooks/wh_a1b2c3d4/disable
Esempio di risposta 200
{
  "id": "wh_a1b2c3d4",
  "endpoint": "https://example.com/hooks/contit",
  "enabled": false
}
Prova 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.

Richiede la policy WriteAccess

Parametri del percorso

NomeTipoObbligatorioDescrizione
idstringWebhook ID

Risposte

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

Esempi di codice

curl -X POST "https://api.contit.cloud/webhooks/{id}/rotate-secret" \
  -H "X-Api-Key: YOUR_API_KEY"
Esempio di richiesta
POST /webhooks/wh_a1b2c3d4/rotate-secret
Esempio di risposta 200
{
  "id": "wh_a1b2c3d4",
  "endpoint": "https://example.com/hooks/contit",
  "secret": "wh_NEWa7f3e1d2c9b6...",
  "enabled": true
}
Prova 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.

Richiede la policy WriteAccess

Parametri del percorso

NomeTipoObbligatorioDescrizione
idstringWebhook ID

Risposte

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

Esempi di codice

curl -X POST "https://api.contit.cloud/webhooks/{id}/test" \
  -H "X-Api-Key: YOUR_API_KEY"
Esempio di richiesta
POST /webhooks/wh_a1b2c3d4/test
Esempio di risposta 200
{
  "isSuccessStatusCode": true,
  "statusCode": 200,
  "message": "{\"ok\":true}",
  "durationMs": 184
}
Prova 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.

Richiede la policy ReadAccess

Parametri del percorso

NomeTipoObbligatorioDescrizione
idstringWebhook ID

Parametri della query

NomeTipoObbligatorioDescrizione
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)

Risposte

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

Esempi di codice

curl -X GET "https://api.contit.cloud/webhooks/{id}/events" \
  -H "X-Api-Key: YOUR_API_KEY"
Esempio di richiesta
GET /webhooks/wh_a1b2c3d4/events?page=1&pageSize=20&status=-1
Esempio di risposta 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
}
Prova 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.

Richiede la policy ReadAccess

Parametri del percorso

NomeTipoObbligatorioDescrizione
idstringWebhook ID
eventIdstringDelivery ID

Risposte

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

Esempi di codice

curl -X GET "https://api.contit.cloud/webhooks/{id}/events/{eventId}" \
  -H "X-Api-Key: YOUR_API_KEY"
Esempio di richiesta
GET /webhooks/wh_a1b2c3d4/events/evt_9b8c7d6e5f4a
Esempio di risposta 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"
}
Prova 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.

Richiede la policy WriteAccess

Parametri del percorso

NomeTipoObbligatorioDescrizione
idstringWebhook ID
eventIdstringDelivery ID to retry

Risposte

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

Esempi di codice

curl -X POST "https://api.contit.cloud/webhooks/{id}/events/{eventId}/retry" \
  -H "X-Api-Key: YOUR_API_KEY"
Esempio di richiesta
POST /webhooks/wh_a1b2c3d4/events/evt_9b8c7d6e5f4a/retry
Prova 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.

Richiede la policy WriteAccess

Parametri del percorso

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

Risposte

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

Esempi di codice

curl -X POST "https://api.contit.cloud/webhooks/{id}/generate-sample/{contentTypeId}" \
  -H "X-Api-Key: YOUR_API_KEY"
Esempio di richiesta
POST /webhooks/wh_a1b2c3d4/generate-sample/article
Prova Live