Content Actions

Le Content Actions permettono di attivare chiamate HTTP esterne (webhook, workflow n8n, Zapier, ecc.) direttamente da un contenuto. Le azioni sono configurate sul Content Type e possono funzionare in due modalita': sincrona e asincrona con callback.

Endpoint

Metodo	Endpoint	Descrizione
GET	/actions/{contentTypeKey}/{contentId}/{actionId}/execute	Esegui un'azione
GET	/actions/{contentTypeKey}/{contentId}/{actionId}/navigate	Esegui un'azione di navigazione (ritorna URL)
GET	/actions/{contentTypeKey}/{contentId}/{actionId}/status	Stato dell'esecuzione (solo modalita' callback)
POST	/actions/callback/{workspaceId}/{operationId}	Endpoint di callback per servizi esterni

Modalita' sincrona (default)

Quando UseCallback e' disabilitato sull'azione, l'esecuzione e' sincrona: Contit chiama il servizio esterno, attende la risposta e ritorna il risultato immediatamente.

Client --> GET /actions/{type}/{id}/{actionId}/execute
        --> Contit chiama il servizio esterno
        <-- Il servizio esterno risponde
<-- Risposta con risultato

Esempio

curl -H "Authorization: Bearer {token}" \
  "https://api.contit.cloud/actions/orders/abc123/send-email/execute"

Risposta:

"OK"

Modalita' asincrona con callback

Quando UseCallback e' abilitato sull'azione, l'esecuzione diventa asincrona: Contit crea un record di tracciamento, chiama il servizio esterno passando un callbackUrl, e ritorna immediatamente con stato Running. Il servizio esterno processa la richiesta e poi chiama il callbackUrl per comunicare il risultato.

Client --> GET /actions/{type}/{id}/{actionId}/execute
        --> Contit crea record esecuzione (Running)
        --> Contit chiama il servizio esterno (con callbackUrl nel payload)
        <-- Il servizio esterno risponde 2xx (accettato)
<-- Risposta: { operationId, callbackUrl }

Client --> GET /actions/{type}/{id}/{actionId}/status  (polling)
<-- Risposta: { status: "Running", progress: 50, message: "Elaborazione..." }

Servizio esterno --> POST /actions/callback/{workspaceId}/{operationId}
                     { "success": true, "result": "completato" }
<-- 200 OK

Client --> GET /actions/{type}/{id}/{actionId}/status  (polling)
<-- Risposta: { status: "Succeeded", result: "completato" }

Risposta execute (modalita' callback)

{
  "operationId": "d4f5a6b7-...",
  "callbackUrl": "https://api.contit.cloud/actions/callback/ws-123/d4f5a6b7-..."
}

Risposta status

curl -H "Authorization: Bearer {token}" \
  "https://api.contit.cloud/actions/orders/abc123/send-email/status"

{
  "operationId": "d4f5a6b7-...",
  "status": "Running",
  "progress": 50,
  "message": "Elaborazione ordine...",
  "result": null,
  "error": null,
  "updatedAt": "2026-04-02T10:30:00Z"
}

Valori dello stato: Running (0), Succeeded (1), Failed (-1)

Prevenzione duplicati

Se un'azione con UseCallback e' gia' in esecuzione per lo stesso contenuto e la stessa azione, l'endpoint execute ritorna 409 Conflict.

Endpoint di callback

L'endpoint di callback viene chiamato dal servizio esterno (n8n, Zapier, ecc.) per comunicare il risultato. Non richiede autenticazione — la sicurezza e' basata sull'ID operazione non prevedibile (GUID).

`POST /actions/callback/

Completare l'azione (successo):

{
  "success": true,
  "result": "Ordine elaborato con successo",
  "message": "Completato"
}

Completare l'azione (errore):

{
  "success": false,
  "error": "Timeout gateway di pagamento",
  "message": "Pagamento fallito"
}

Aggiornamento di progresso intermedio:

{
  "success": true,
  "progress": 50,
  "message": "Elaborazione articoli..."
}

Quando progress e' inferiore a 100, l'esecuzione resta in stato Running e vengono aggiornati solo progress e message. Questo permette al servizio esterno di inviare piu' aggiornamenti di progresso prima del completamento finale.

Campi della richiesta di callback

Campo	Tipo	Descrizione
success	bool	true per successo, false per errore
result	string	Dati del risultato (ritornati al client in caso di successo)
error	string	Messaggio di errore (ritornato al client in caso di fallimento)
message	string	Messaggio di stato visualizzato nella UI
progress	int?	Percentuale di progresso (0-100). Valori < 100 aggiornano il progresso senza completare

Come viene consegnato il callbackUrl

Il callbackUrl viene incluso nella richiesta al servizio esterno in base alla modalita' di payload dell'azione:

Modalita' Payload	Come viene consegnato il callbackUrl
None (GET)	Aggiunto come query parameter: ?callbackUrl=...
IdOnly	Campo nel body JSON: { "id": "...", "callbackUrl": "..." }
FullEntity	Campo nel body JSON: { "id": "...", "fields": {...}, "callbackUrl": "..." }
CustomTemplate	Disponibile nel template come {{callbackUrl}}

Esempio payload (IdOnly)

{
  "id": "abc123",
  "contentType": "orders",
  "workspaceId": "ws-xyz",
  "callbackUrl": "https://api.contit.cloud/actions/callback/ws-xyz/d4f5a6b7-..."
}

Esempio integrazione n8n

1. Configura l'azione sul Content Type:

   • Imposta l'URL template con l'URL del webhook n8n
   • Imposta la modalita' payload su IdOnly o FullEntity
   • Abilita UseCallback

2. Workflow n8n:

   • Nodo Webhook trigger riceve il payload (incluso callbackUrl)
   • Processa i vari step del workflow
   • Nodo HTTP Request finale: POST su {{ $json.callbackUrl }} con body:

     { "success": true, "result": "Completato" }
     

3. Aggiornamenti di progresso opzionali:

   • Aggiungi nodi HTTP Request intermedi durante workflow lunghi:

     { "success": true, "progress": 30, "message": "Step 1 completato" }
     

Ciclo di vita dell'esecuzione

I record di esecuzione scadono automaticamente dopo 1 ora. Se il servizio esterno non chiama il callback entro questo tempo, il record viene rimosso e l'azione puo' essere rieseguita.