Create a webhook endpoint

POST/webhooks

Creates a webhook endpoint that receives events for the subscribed event types.

The destination URL must use HTTPS and point to a public host on port 443, 80, or 8443. Private IP addresses and other non-public destinations are rejected before the endpoint is created, in sandbox accounts too.

The response includes the signing secret. It is returned only once and cannot be retrieved again.

Setting payload_detail to full requires the personal data permissions described in that field. Without them, the request fails with 403 and the error code personal_data_permission_required, and the endpoint is not created.

Authorization

AuthorizationBearer <token>

Credential: the API credential secret, sent as a bearer token. Credential secrets are identified by a fixed prefix.

In: header

Header Parameters

Idempotency-Key*string

Client-generated key that makes the request safe to retry. Must be 1 to 128 characters from [A-Za-z0-9._:-]. Required by this operation: a missing key returns idempotency_key_required, and a malformed key returns idempotency_key_invalid. Repeating the request with the same key and the same body returns the stored result with Idempotent-Replayed: true.

X-Client-Request-Id?string

Optional client-generated identifier of the request, up to 64 characters from [A-Za-z0-9._-]. Echoed back in the response and recorded in the request log; it never replaces the server-generated X-Request-Id.

Lengthlength <= 64

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

description?string|null

event_filters?|

Restricts which events of each event type the endpoint receives, by fields of the event. Each key is one of the event_types of the endpoint, and its value holds the filters for that event type; event types without a key are delivered without these filters. An event is delivered only when it passes both resource_filters and the filters of its event type. The request fails with 422 and the error code validation_failed when a key is not an event type of the endpoint or does not accept filters, or when a filter is not accepted for that event type or has an invalid value; details[].field points to it, such as event_filters.exam_attempt.completed.passed. The object replaces the current filters as a whole, and null or an empty object removes them. When an update changes event_types without sending event_filters, the filters of the event types removed are dropped.

event_types*array<string>

Items1 <= items

payload_detail?string

How much detail each delivery carries, for all event types of the endpoint. ids (the default) sends the event data only, which identifies people by ID and carries no personal data stored by Cademí; its only free text is the note written by whoever operates the account (reason in certificate.revoked and diamond_membership.stage_changed), sent as written. masked and full add an expanded object next to data, with the resources the event refers to (such as user, product and lesson) in the same format the API returns them. In masked, each personal field keeps its type and is masked by fixed rules. A name keeps its first word, and each other word becomes its first letter followed by ** (Renan C** P**). An email keeps the first two characters of the user part (one, when it has two or fewer) and the first letter of the first domain label, each followed by **, and the other domain labels (re**@g**.com). A phone keeps only digits: with 10 or more, the area code in parentheses, ***** and the last four (a leading 55 of a 12 or 13 digit number is dropped); with 4 to 9, ***** and the last four; with fewer, **** ((13) *****8923). A document keeps only its last two digits (***.***.***-09 for an 11 digit CPF, one * for each other digit otherwise). external_id, the IP address and user agent of a legal term acceptance, and the address and custom field values recorded in a certificate become [redacted], and so does free text written by users (the text of a comment, the body of a question, the subject of a ticket). null stays null, empty text stays empty, a name made only of spaces is sent as it is, an email without @ is masked as a user part, and a document without digits becomes empty. Masked personal data is still personal data. In full, values are sent as stored. Setting full requires the users.read_personal permission, plus tickets.read_personal when an event type expands a ticket and legal_terms.read_proof when an event type expands a term_acceptance.

Default"ids"

Value in

"ids"
"masked"
"full"

resource_filters?|

Restricts which events the endpoint receives, per resource type. Each key is the resource type of an event type, as listed in the event catalog (such as product or lesson), and each value lists the IDs of that type to deliver, as public IDs (prd_7) or numeric IDs (7). A filter applies only to events whose own resource is of that type: lesson_progress.completed is about a lesson, so a product filter does not restrict it. Events whose resource type is not a key are delivered without restriction. null removes all filters.

url*string

Formaturi

Response Body

`application/json`

curl -X POST "https://example.com/webhooks" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "event_types": [      "string"    ],    "url": "http://example.com"  }'

{  "data": {    "created_at": "2019-08-24T14:15:22Z",    "description": "string",    "event_filters": {      "property1": {        "added_tag_id": [          0        ],        "custom_field_id": [          0        ],        "delivery_id": [          0        ],        "exam_id": [          0        ],        "filled": true,        "legal_term_id": [          "string"        ],        "lesson_id": [          0        ],        "milestones": [          50        ],        "min_percent": 0,        "origin": [          "lesson_completed"        ],        "passed": true,        "product_id": [          0        ],        "signup_origin": "paid"      },      "property2": {        "added_tag_id": [          0        ],        "custom_field_id": [          0        ],        "delivery_id": [          0        ],        "exam_id": [          0        ],        "filled": true,        "legal_term_id": [          "string"        ],        "lesson_id": [          0        ],        "milestones": [          50        ],        "min_percent": 0,        "origin": [          "lesson_completed"        ],        "passed": true,        "product_id": [          0        ],        "signup_origin": "paid"      }    },    "event_types": [      "string"    ],    "health": {      "circuit_state": "closed",      "consecutive_failures": 0,      "dead_24h": 0,      "delivered_24h": 0,      "effective_payload_detail": "ids",      "failed_24h": 0,      "last_failure_at": "2019-08-24T14:15:22Z",      "last_success_at": "2019-08-24T14:15:22Z",      "pending": 0    },    "id": "string",    "max_per_second": 0,    "object": "webhook",    "payload_detail": "ids",    "payload_version": 0,    "resource_filters": {      "property1": [        0      ],      "property2": [        0      ]    },    "revision": 0,    "secret": "string",    "status": "active",    "timeout_ms": 0,    "updated_at": "2019-08-24T14:15:22Z",    "url": "http://example.com"  }}

Create a webhook endpoint

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

406application/json

409application/json

413application/json

415application/json

422application/json

429application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`