Update a webhook endpoint

PATCH/webhooks/{webhook_id}

Updates the URL, subscribed event types, resource filters, event filters, description, payload detail level, or status of a webhook endpoint.

Changing status requires the webhooks.activate permission in addition to webhooks.update. A new URL is subject to the same destination restrictions as the create operation.

Changing payload_detail to full, or changing the event types of an endpoint whose payload_detail is 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 nothing is changed. Deliveries already queued keep the expanded object built when they were created, and send it only while the endpoint still accepts that level: after lowering the level, a retry is sent without expanded.

Setting status to active on an endpoint that the platform deactivated after repeated delivery failures reactivates it: its failure count is reset, and deliveries from the last 48 hours that ended as dead or were canceled by the deactivation go back to the queue. Setting status to inactive on such an endpoint does not change it.

Send the ETag returned by the retrieve operation in the If-Match header to avoid overwriting changes made since the endpoint was retrieved. If the header is omitted, the update is applied to the current revision.

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

webhook_id*string

Public ID of the webhook, prefixed with whk_.

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._:-]. Optional on this operation; when sent, a malformed key returns idempotency_key_invalid, and repeating the request with the same key and the same body returns the stored result with Idempotent-Replayed: true.

If-Match?string

Expected revision of the resource, in the same format as the ETag header (W/"<type>:<id>:<revision>"). If the resource has changed since that revision, the request fails with 412 and the revision_mismatch error code. * matches the current revision. Any other value fails with 400 and the if_match_invalid error code. When omitted, the update is applied to the current revision.

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>

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.

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.

status?string

Value in

"active"
"inactive"

url?string

Formaturi

Response Body

`application/json`

curl -X PATCH "https://example.com/webhooks/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "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"  }}

Update a webhook endpoint

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

406application/json

409application/json

412application/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`

`application/json`

`application/json`