Events

Requests the gateway stored. Authentication, errors and limits are on the overview.

Revoke event share

DELETE /api/v1/projects/{project_id}/environments/{environment_id}/event-shares/{share_id}

The link stops working at once.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
share_id required	path	string	shr_ ID

Responses

Status	Description	Body
204	Revoked
401	No API key, or it is invalid or revoked	Problem
404	No such link, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

List events

GET /api/v1/projects/{project_id}/environments/{environment_id}/events

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
source_id	query	string	Only this source's events (src_ ID).
status	query	string	received, pending, delivered or failed.
event_type	query	string	Only events of this type, exactly.
verification	query	string	verified, not_configured or failed.
after	query	string (date-time)	Received at or after this time.
before	query	string (date-time)	Received before this time.
cursor	query	string	From a previous page's next_cursor.
had_failed_attempt	query	boolean	true: only events with a failed attempt on an original delivery (no response, or one that was not a 2xx), even when a retry then succeeded.
error_kind	query	string	Only events with a failed attempt of this kind on an original delivery: one of the kinds of AttemptError.
destination_id	query	string	Only events with an original delivery to this destination (dst_ ID). With had_failed_attempt or error_kind, the failed attempt must be one of that delivery's.
search	query	string	Events found by an ID or a value (P4-09): an evt_ or dlv_ ID, a request ID, the provider's event ID, or the value of one of the source's search fields, exactly.
field	query	string	With search, only this search field's value (body.data.customer).
limit	query	integer (int64)	Page size: 1 to 100, default 50.

Responses

Status	Description	Body
200	One page, newest first	EventPage
401	No API key, or it is invalid or revoked	Problem
404	No such environment, or no access	Problem
422	Invalid filter or cursor	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Export events

GET /api/v1/projects/{project_id}/environments/{environment_id}/events/export

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
format	query	string	jsonl (default) or csv.
columns	query	string	For CSV, extra columns after the event's own, comma separated: body.<key>... (an array item by its number, as in body.items.0.id), body or headers.<name>. At most 50.
source_id	query	string	Only this source's events (src_ ID).
status	query	string	received, pending, delivered or failed.
event_type	query	string	Only events of this type, exactly.
verification	query	string	verified, not_configured or failed.
after	query	string (date-time)	Received at or after this time.
before	query	string (date-time)	Received before this time.
had_failed_attempt	query	boolean	As in the events list.
error_kind	query	string	As in the events list.
destination_id	query	string	As in the events list (dst_ ID).
search	query	string	As in the events list.
field	query	string	As in the events list.

Responses

Status	Description	Body
200	Every matching event, newest first, as a download. JSON Lines: one event per line, its summary with headers, body and body_encoding (json, text or base64). CSV: the event's own columns, then the chosen ones; a cell that a spreadsheet would read as a formula starts with '
401	No API key, or it is invalid or revoked	Problem
404	No such environment, or no access	Problem
422	Invalid filter, format or column	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Get event

GET /api/v1/projects/{project_id}/environments/{environment_id}/events/{event_id}

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
event_id required	path	string	evt_ ID

Responses

Status	Description	Body
200	The event, its request and its deliveries	Event
401	No API key, or it is invalid or revoked	Problem
404	No such event, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Release event

POST /api/v1/projects/{project_id}/environments/{environment_id}/events/{event_id}/release

Routes a quarantined event to its connections as if it had passed verification. It keeps its verification result.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
event_id required	path	string	evt_ ID

Responses

Status	Description	Body
200	Released: its deliveries are queued	Released
401	No API key, or it is invalid or revoked	Problem
404	No such event, or no access	Problem
409	The event is not quarantined	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The gateway is not answering	Problem

Resend event

POST /api/v1/projects/{project_id}/environments/{environment_id}/events/{event_id}/resend

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
event_id required	path	string	evt_ ID of the original

Request body

JSON, SendTestEvent.

Field	Type	Description
body required	string	The raw body, as the provider would send it; at most 60,000 bytes.
headers	string[][] | null	[name, value] pairs, in order; at most 100. Ricochet adds the signature unless sign is false.
method	string | null	One the source accepts. Default POST.
sign	boolean | null	Sign it with the source's newest secret, as its verification method expects. Default true; false sends it exactly as given.

Responses

Status	Description	Body
201	The copy, stored and routed unless it was held	TestEvent
401	No API key, or it is invalid or revoked	Problem
404	No such event, or no access	Problem
409	The event's source no longer exists	Problem
422	An invalid request, a method the source refuses, or nothing to sign with	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The gateway is not answering	Problem

List event shares

GET /api/v1/projects/{project_id}/environments/{environment_id}/events/{event_id}/shares

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
event_id required	path	string	evt_ ID

Responses

Status	Description	Body
200	The links that still work	ShareList
401	No API key, or it is invalid or revoked	Problem
404	No such environment, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Share event

POST /api/v1/projects/{project_id}/environments/{environment_id}/events/{event_id}/shares

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
event_id required	path	string	evt_ ID

Request body

JSON, CreateShare.

Field	Type	Description
expires_in_hours	integer (int32) | null	How long the link works: 1 to 720 hours; 168 (a week) when left out.

Responses

Status	Description	Body
201	The link, shown once	NewShare
401	No API key, or it is invalid or revoked	Problem
404	No such event, or no access	Problem
422	An expiry out of range	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Check event signature

POST /api/v1/projects/{project_id}/environments/{environment_id}/events/{event_id}/signature-check

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
event_id required	path	string	evt_ ID

Request body

JSON, CheckSignature.

Field	Type	Description
secret	string | null	A secret to check with, as the provider shows it; omitted, the source's current secrets.

Responses

Status	Description	Body
200	The result and its steps, under the source's current settings, as of when the event arrived	SignatureCheck
401	No API key, or it is invalid or revoked	Problem
404	No such event, or no access	Problem
409	The source is gone, or has no current secret	Problem
422	An empty or too long secret	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The gateway is not answering	Problem

List issues

GET /api/v1/projects/{project_id}/environments/{environment_id}/issues

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
after	query	string (date-time)	Events received at or after, default 7 days before before.
before	query	string (date-time)	Events received before, default now. At most 31 days after after.

Responses

Status	Description	Body
200	Failed deliveries by destination and cause	IssueList
401	No API key, or it is invalid or revoked	Problem
404	No such environment, or no access	Problem
422	Invalid range	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem