Test an event subscription
const url = 'https://api.getsitecontrol.com/v1/sites/1/event-subscriptions/1/test';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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/1/test \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "event_type": "example" }'Sends a sample event to the receiver for real: signed, through the same queue as live events, once and without retries. Waits up to 20 seconds for the answer. Call it after creating or changing an event subscription to check the receiver end to end. Works on an inactive event subscription too. Returns the sample kind and the delivery with its attempts: the receiver’s status code and the first 16 KB of its answer. 200 when the delivery finished; 202 with the same body, status: pending and the Location of the delivery otherwise: read it later with get_event_subscription_delivery.
The sample is chosen as in preview_event_subscription. A template that fails on the sample gives a failed delivery with outcome invalid_request. Tests are listed in the journal with is_test: true, do not change last_success_at or last_failure_at and cannot be redelivered. Needs edit. Spends the heavy request limit.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Event subscription id from list_event_subscriptions
Event subscription id from list_event_subscriptions
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 Body
Section titled “Request Body”object
The event to use, one of the event subscription’s events; the first when left out
{ "event_type": "example"}Responses
Section titled “Responses”object
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
object
Delivery id, sent as the webhook-id header: the same on every retry, new on a redelivery
id of the event in the payload: the same for every event subscription and every redelivery of the event
Null once the event is purged
True for a delivery of test_event_subscription
Pending: waiting for an attempt or being sent; succeeded: accepted by the
receiver; failed: given up, see outcome; cancelled: dropped before sending
because the event subscription was deleted, switched off or saved since, or
its URL host changed.
How a finished delivery ended. accepted: the receiver answered 2xx, 302 or 303, which is not proof it processed the event; rejected: another 4xx, or 301, 307, 308 and other 3xx (the receiver moved, see the attempt’s location), not retried; gone: 410; retry_exhausted: every retry failed; expired: no time left for a retry; rate_limited: the receiver’s 429 pause ran past the deadline; invalid_request: the request could not be built, e.g. a template failed on the event (last_error says why); private_network_block: the host resolved to a private address; cancelled: see status. More values may appear
Requests sent so far
HTTP status of the last attempt’s answer; null without an answer
What went wrong last, e.g. HTTP 500 or render failed: ...
When the next attempt is due; null once finished
When it finished; null while pending
The delivery this one redelivers
The request as stored, masked
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
Every attempt, the first one first
object
1 for the first request of a delivery
Accepted: 2xx, 302 or 303; retryable: 408, 5xx, a timeout or a network error, may be tried again; rate_limited: 429; rejected: another 4xx, or 301, 307, 308 and other 3xx; gone: 410. More values may appear
HTTP status of the receiver’s answer; null without an answer
The first 16 KB of the receiver’s answer
True when the answer was longer than response_body
The receiver’s Retry-After header, honoured for the next try
The receiver’s Location header; redirects are not followed
What went wrong, e.g. HTTP 500 or a network error
{ "delivery": { "status": "pending" }}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
object
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
object
Delivery id, sent as the webhook-id header: the same on every retry, new on a redelivery
id of the event in the payload: the same for every event subscription and every redelivery of the event
Null once the event is purged
True for a delivery of test_event_subscription
Pending: waiting for an attempt or being sent; succeeded: accepted by the
receiver; failed: given up, see outcome; cancelled: dropped before sending
because the event subscription was deleted, switched off or saved since, or
its URL host changed.
How a finished delivery ended. accepted: the receiver answered 2xx, 302 or 303, which is not proof it processed the event; rejected: another 4xx, or 301, 307, 308 and other 3xx (the receiver moved, see the attempt’s location), not retried; gone: 410; retry_exhausted: every retry failed; expired: no time left for a retry; rate_limited: the receiver’s 429 pause ran past the deadline; invalid_request: the request could not be built, e.g. a template failed on the event (last_error says why); private_network_block: the host resolved to a private address; cancelled: see status. More values may appear
Requests sent so far
HTTP status of the last attempt’s answer; null without an answer
What went wrong last, e.g. HTTP 500 or render failed: ...
When the next attempt is due; null once finished
When it finished; null while pending
The delivery this one redelivers
The request as stored, masked
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
Every attempt, the first one first
object
1 for the first request of a delivery
Accepted: 2xx, 302 or 303; retryable: 408, 5xx, a timeout or a network error, may be tried again; rate_limited: 429; rejected: another 4xx, or 301, 307, 308 and other 3xx; gone: 410. More values may appear
HTTP status of the receiver’s answer; null without an answer
The first 16 KB of the receiver’s answer
True when the answer was longer than response_body
The receiver’s Retry-After header, honoured for the next try
The receiver’s Location header; redirects are not followed
What went wrong, e.g. HTTP 500 or a network error
{ "delivery": { "status": "pending" }}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 delivery to read later
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
event_subscription_not_found: no event subscription with this id on the site; site_not_found: no such site
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: event_type is not one of the event subscription’s 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