Skip to main content
POST
/
webhooks
Register a webhook
curl --request POST \
  --url https://api.godiligent.ai/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "webhook_url": "<string>",
  "is_active": true,
  "secret": "<string>",
  "events": []
}
'
{
  "id": "<string>",
  "webhook_url": "<string>",
  "is_active": true,
  "has_secret": true,
  "last_delivery_at": "2023-11-07T05:31:56Z",
  "last_delivery_status": 123,
  "events": []
}

​
Endpoint

POST /webhooks Creates a new webhook endpoint for the authenticated customer. You can register up to 10 webhooks, each with its own URL, secret, and event filter. Event delivery fans out to every active webhook whose filter matches the event.
Behavior change: this endpoint previously upserted a single webhook per customer — repeated POSTs updated the same record. It now always creates a new webhook. To modify an existing webhook, use PATCH /webhooks/{webhook_id}. To remove one, use DELETE /webhooks/{webhook_id}.

​
Request Body

JSON object with the following fields:
FieldTypeRequiredDescription
webhook_urlstringYesHTTPS URL to receive webhook events. Must start with https://.
secretstringNoSecret used to sign webhook payloads (X-Signature header). Write-only — never returned by the API. Empty string is treated as no secret.
is_activebooleanNoWhether the webhook is active. Defaults to true.
eventsstring[]NoList of event types to subscribe to. Defaults to an empty list (no events).

​
Supported Event Types

  • cdd_state_changed: When the state of a CDD changes to either inconclusive or complete.
  • monitoring_alert_fired: When a monitoring alert is fired on failure.
  • cdd_document_fetched: When a new document is successfully added to a CDD case.
  • search_completed: When a name screening search completes and results are available.
  • alert_remediated: When a name screening alert has been remediated (all hits resolved).
  • flow_run_completed: When a flow run finishes successfully (COMPLETED).
  • flow_run_failed: When a flow run fails (FAILED).

​
Example Request

{
  "webhook_url": "https://www.testing-webhooks.com",
  "is_active": true,
  "secret": "some-secret",
  "events": ["cdd_state_changed", "monitoring_alert_fired", "search_completed"]
}

​
Responses

​
201 Created

The webhook was created. The response body is the created webhook (the secret is never echoed — has_secret indicates whether one is set). 
{
  "id": "df89eb16-4c6a-439f-b668-7cca0cd786fa",
  "webhook_url": "https://www.testing-webhooks.com",
  "is_active": true,
  "has_secret": true,
  "status": "active",
  "last_delivery_at": null,
  "last_delivery_status": null,
  "events": ["cdd_state_changed", "monitoring_alert_fired", "search_completed"]
}

​
400 Bad Request

Input validation failed. 
{
  "error": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "number",
      "path": ["webhook_url"],
      "message": "Expected string, received number"
    }
  ]
}

​
409 Conflict

The customer already has the maximum of 10 webhooks. Delete one before creating another. 
{
  "error": "Webhook limit reached (max 10 per customer)"
}

​
500 Internal Server Error

Unexpected error occurred. 
{
  "error": "Internal server error"
}

​
Authentication

This endpoint requires authentication. The webhook is associated with the authenticated customer.

Authorizations

​
X-API-KEY
string
header
required

Body

application/json
​
webhook_url
string<uri>
required

Must be a valid URL starting with https.

​
is_active
boolean
default:true

Indicates if the webhook is active.

​
secret
string

Secret used to sign the webhook payload, passed in the X-Signature header. Write-only — it is never returned by the API.

​
events
enum<string>[]

List of events to trigger the webhook. If not provided, no events will be triggered.

cdd_state_changed: When the state of a CDD changes to either inconclusive or complete. monitoring_alert_fired: When a monitoring alert is fired on failure. cdd_document_fetched: When a new document is successfully added to a CDD case. search_completed: When a name screening search completes and results are available. alert_remediated: When a name screening alert has been remediated. flow_run_completed: When a flow run finishes successfully (COMPLETED). flow_run_failed: When a flow run fails (FAILED).

Available options:
cdd_state_changed,
monitoring_alert_fired,
cdd_document_fetched,
search_completed,
alert_remediated,
flow_run_completed,
flow_run_failed

Response

Webhook created.

​
id
string

Unique ID for the webhook.

​
webhook_url
string<uri>
​
is_active
boolean
​
has_secret
boolean

Whether a signing secret is configured. The secret itself is never returned.

​
status
enum<string>

Derived health: disabled when inactive, failing when the last delivery returned a non-2xx status, otherwise active.

Available options:
active,
failing,
disabled
​
last_delivery_at
string<date-time> | null

Timestamp of the most recent delivery attempt, or null if none.

​
last_delivery_status
integer | null

HTTP status code of the most recent delivery attempt, or null if none.

​
events
enum<string>[]
Available options:
cdd_state_changed,
monitoring_alert_fired,
cdd_document_fetched,
search_completed,
alert_remediated,
flow_run_completed,
flow_run_failed