CIcint
Notifications Webhooks

Creates a new webhook for an account

Creates a new webhook subscription for an account. This allows your application to receive real-time notifications for specific events.

post/accounts/{account_id}/webhooks

Request

Request body

urlstring url required

The HTTPS endpoint where webhook notifications will be sent.

eventsWebhookEventType[] required

An array of webhook event type names.

compression'gzip' | 'null' nullable

The compression applied to the body of every webhook request for this subscription.

To receive compressed request bodies, set this field to gzip. Each request then carries the Content-Encoding: gzip header. The Content-Type header remains application/json, because compression changes only how the body is encoded, not its media type.

Compression is not enabled by default. To receive uncompressed request bodies, omit this field, or set it to null or an empty string.

Updating a webhook replaces the subscription, so an update that omits compression disables it. To keep compression enabled, include the field in every update.

Example request

{
  "url": "https://example.com/webhook",
  "events": [
    "target-group-updated",
    "quota-fill-registered"
  ],
  "compression": "gzip"
}

Response

The webhook was created successfully.

Important: The secret is only returned on creation. You must store it securely, as you will need it to verify the signature of incoming webhook requests.

idstring ulid

The ID of the webhook.

urlstring url

The HTTPS endpoint where webhook notifications will be sent.

eventsWebhookEventType[]

An array of webhook event type names.

compression'gzip' | 'null' nullable

The compression applied to the body of every webhook request for this subscription.

To receive compressed request bodies, set this field to gzip. Each request then carries the Content-Encoding: gzip header. The Content-Type header remains application/json, because compression changes only how the body is encoded, not its media type.

Compression is not enabled by default. To receive uncompressed request bodies, omit this field, or set it to null or an empty string.

Updating a webhook replaces the subscription, so an update that omits compression disables it. To keep compression enabled, include the field in every update.

secretstring base64

This is your webhook's secret signing key. You must use it to verify the authenticity and integrity of incoming webhook requests.

Each webhook request includes a Cint-Signature header with two components:

  • t (timestamp): A Unix timestamp representing the time of the webhook call.

  • v1 (signature v1): An HMAC SHA256 hash of the payload, generated by signing it with the secret key.

The payload used to create the signature is the concatenation of the timestamp (t) and the request body, separated by a period (.). For example:

  • Payload: 1732526080.{"foo":"bar"}

  • Example of Cint-Signature header:

Cint-Signature: t=1732526080,v1=6532d4777122acc32cd388763fc0c0ba8732698d09cf99eea086e5a86f8d3ebe

To verify the signature, you can use the following CLI command:

$ export PAYLOAD='1732526080.{"foo":"bar"}'
$ export SECRET=FP7UPZpATKBcYJj4va95PYud+a3gCidRERiLO+9MoFE=
$ echo -n $PAYLOAD | openssl dgst -sha256 -hmac $SECRET
# => (stdin)= 6532d4777122acc32cd388763fc0c0ba8732698d09cf99eea086e5a86f8d3ebe

If the subscription sets compression, the request body is compressed on the wire, but the signature still covers the uncompressed JSON, so this verification is unchanged.

created_atstring date-time

The timestamp when the webhook was created, in RFC3339 UTC format.

updated_atstring date-time

The timestamp when the webhook was last updated, in RFC3339 UTC format.

Example response

{
  "id": "01JPVZD75DW4KRP7MPFMF6KGZX",
  "url": "https://example.com/webhook",
  "events": [
    "target-group-updated",
    "quota-fill-registered"
  ],
  "compression": "gzip",
  "secret": "FP7UPZpATKBcYJj4va95PYud+a3gCidRERiLO+9MoFE=",
  "created_at": "2023-01-01T23:00:00.000Z",
  "updated_at": "2023-01-01T23:05:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.