Preview an unsaved event subscription
const url = 'https://api.getsitecontrol.com/v1/sites/1/event-subscriptions/preview';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","events":["example"],"filter":{"widget_ids":[1]},"url":"example","method":"POST","format":"json","headers":[{"name":"example","value":"example","is_secret":false}],"body":"example","event_type":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.getsitecontrol.com/v1/sites/1/event-subscriptions/preview \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "events": [ "example" ], "filter": { "widget_ids": [ 1 ] }, "url": "example", "method": "POST", "format": "json", "headers": [ { "name": "example", "value": "example", "is_secret": false } ], "body": "example", "event_type": "example" }'Renders the request an unsaved event subscription configuration would send, and saves and sends nothing. Takes the same body as create_event_subscription, plus event_type. Call it to check a URL or body template before create_event_subscription.
The sample is the latest response of the filtered widgets, or the latest contact, from the last 30 days, otherwise a made-up one (sample). payload is the default payload of the sample: the data a template reads. A template that fails on the sample gives render_error and request: null. Secret header values read ***. Needs view of the events’ sections. Spends the heavy request limit.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Header Parameters
Section titled “Header Parameters”Makes a retry of a POST safe: a repeat with the same key, body and GSC-Version returns the stored response with Idempotency-Replayed: true instead of running again. The key protects against repeated execution while the key store works. Saving the change and storing the response under the key are not atomic: if the process or the key store fails between them, the change is kept, the key is released after 15 minutes and a retry runs the request again. After a timeout or a 5xx, read the resource to check the result before retrying. 5xx and 429 responses and responses over 256 KB are not stored, so a repeat runs the request again. A key is kept for 24 hours. The same key with another body or version is 422; a repeat while the first request runs is 409.
Makes a retry of a POST safe: a repeat with the same key, body and GSC-Version returns the stored response with Idempotency-Replayed: true instead of running again. The key protects against repeated execution while the key store works. Saving the change and storing the response under the key are not atomic: if the process or the key store fails between them, the change is kept, the key is released after 15 minutes and a retry runs the request again. After a timeout or a 5xx, read the resource to check the result before retrying. 5xx and 429 responses and responses over 256 KB are not stored, so a repeat runs the request again. A key is kept for 24 hours. The same key with another body or version is 422; a repeat while the first request runs is 409.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Your label for the event subscription, at most 100 characters
1 or 2 distinct event types from list_event_types: response.created, a widget response became active; contact.created, a contact was created by a widget submit or through the public API
Which widgets’ responses are sent; every widget by default
object
Only responses of these widgets (ids from list_widgets), at most 100; empty means every widget. Only with response.created
Receiver URL: https only, at most 2000 characters, a public host. Placeholders such as {{ response.fields.email.value }} are allowed in the path and query, never in the scheme, host or port; their values are percent-encoded. Everyone who may read the event subscription sees the URL in full: put secrets in secret headers, not in the URL
HTTP method of the request
Json: an application/json body; form: an application/x-www-form-urlencoded body, the default payload flattened into keys when there is no template
Up to 20 headers sent with every request. Credentials of the receiver go here as secret headers, e.g. {"name": "Authorization", "value": "Bearer ...", "is_secret": true}; a secret value reads ***
object
Header name, e.g. Authorization. Host, Content-Length, Transfer-Encoding, Connection, User-Agent and webhook-* are set by the sender. A Content-Type replaces the one of format
Sent as is, no placeholders; at most 4096 characters, no line breaks. On update, *** in a secret header keeps its stored value
True for credentials: the value is stored encrypted, reads *** everywhere and is masked in the journal
Null sends the default payload of the event (its schema is in list_event_types). Otherwise a JSON object or array sent instead, its strings filled from the event, e.g. {"text": "New lead {{ response.fields.email.value }} from {{ widget.name }}"}. Roots: event, site, contact; for response.created also response (an answer is response.fields.<name>.value), widget and query. A string that is exactly one placeholder keeps the value’s type (number, boolean, list). Filters: default, join, date, lower, upper, url_encode, e.g. {{ contact.first_name | default: '' }}. Keys with dots or dashes: response.fields['first-name'].value. No placeholders in object keys. With format: form the template is a flat object of scalars. At most 16 KB and 10 levels deep; the sent body at most 64 KB. Check it with preview_new_event_subscription or preview_event_subscription
The event to render, one of events; the first when left out
Responses
Section titled “Responses”object
The event rendered
Where the sample comes from. last_response: the latest response of the filtered widgets within 30 days; last_contact: the latest contact within 30 days; synthetic: made up, from the widget’s fields for a response. More values may appear
The default payload of the sample, the template context source
Null when the templates fail on the sample
object
With placeholders filled; in the journal query values read ***
Content-Type sent
Headers set on the event subscription; secret ones read ***, and in the journal Authorization and Cookie too. The webhook-* signature headers are added when sending
object
The body as sent, as text
Why a template failed on the sample; null when it rendered
object
The template that failed: ["url"] or ["body"]
{ "event_type": "example", "sample": "example", "payload": {}, "request": { "method": "example", "url": "example", "content_type": "example", "headers": { "additionalProperty": "example" }, "body": "example" }, "render_error": { "loc": [ "example" ], "message": "example" }}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
True when the response is a stored one, replayed
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Authentication scheme: Bearer
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
validation_failed: every problem of the configuration at once, each with its loc in the body and a message, e.g. an unknown event type, a widget not found, a header the sender sets, a URL that is not public https or a template error; or event_type is not one of events
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Seconds until the bucket refills
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds