The server synchronously POSTs an activation payload:

{ "event": "activation", "code": "<6-char>" } to the configured url using the configured authentication headers and records the outcome on the webhook.

Endpoint:

HTTP Method: POST

Path: /v2/webhooks

Server URL: https://api.propelus.com

Developer Docs: https://propelus.com/developer/webhooks/CreateWebhooks

2xx response → record stored with status: pending, response code: created_not_verified. The caller's endpoint received the 6-character verification code; submit it to POST /v2/webhooks/{webhookId}/activate to transition the webhook to active.
non-2xx / network failure → record stored with status: failed, response code: created_failed. The id is returned in the same response envelope so the caller can PATCH /v2/webhooks/{webhookId} to retry the activation handshake (PATCH always re-runs the handshake when the stored record is failed).

At most one webhook per (client, eventType) may be in active, pending, or failed state at once. Pending and failed records carry a 7-day time-to-live expiry; abandoned records are reaped automatically.

Authentication

Two header-based authentication methods are required:

Header	Type	In	Description
x-api-key	token	header	API key credential
x-client-id	token	header	Client identifier credential

Request Body

Content type: application/json

Field	Type	Required	Description / Constraints
eventType	string	Yes	Type of event that triggers the webhook.
url	string	Yes	URL endpoint where webhook notifications will be sent. Format: uri. Length ≤ 2048.
signature	object \| null	No	Signature configuration for webhook verification.
authentication	object \| null	No	Authentication configuration for webhook endpoint.

eventType allowed values:

"credentialVerified" | "credentialsBatchCompleted" | "credentialMonitored" |

"monitoredCredentialChanged" | "automationStatusChanged" | "entityMonitored" |

"monitoredEntityChanged"

Example Request — JSON

const body = JSON.stringify({
  "eventType": "credentialVerified",
  "url": "https://my.site/externalEvents",
  "signature": {
    "key": "a3f8c92e5d1b4f7a9e6c2d8b3f5a1c4e"
  }
})

fetch("https://api.propelus.com/v2/webhooks", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>",
    "x-client-id": "<your-client-id>"
  },
  body
})

Example Request — cURL

curl -X POST "https://api.propelus.com/v2/webhooks" \
  -H "x-api-key: <your-api-key>" \
  -H "x-client-id: <your-client-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "credentialVerified",
    "url": "https://my.site/externalEvents",
    "signature": {
      "key": "a3f8c92e5d1b4f7a9e6c2d8b3f5a1c4e"
    }
  }'

Responses

201 — Created

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": 201,
  "code": "created_not_verified",
  "detail": "string"
}

Error Responses

Standardized error bodies. Validation-style errors (400, 401, 403, 404, 4XX) include an errors array; each item contains detail, pointer, parameter, header, and code: https://propelus.com/developer/webhooks/CreateWebhooks#response-body

400 — Bad Request

401 — Unauthorized

403 — Forbidden

404 — Not Found

4XX — Client Error

429 — Rate Limited

5XX — Server Error