Sources

Where webhooks come in. Authentication, errors and limits are on the overview.

List sources

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

Parameters

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

Responses

Status	Description	Body
200	Oldest first	Source[]
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

Create source

POST /api/v1/projects/{project_id}/environments/{environment_id}/sources

A new source, which accepts any request unless verification says otherwise.

Parameters

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

Request body

JSON, CreateSource.

Field	Type	Description
deduplication	Deduplication | null
handshake	Handshake | null	Defaults to none.
methods	Method[] | null	Defaults to ["POST"].
name required	string
response	SourceResponse | null	Defaults to 200 with an empty body.
search_fields	string[] | null	Up to 5 fields its events can be searched by; none by default.
verification	Verification | null	Defaults to {"method": "none"}: every request is accepted.

Responses

Status	Description	Body
201	Created	Source
401	No API key, or it is invalid or revoked	Problem
404	No such environment, or no access	Problem
422	Invalid name, methods, response, verification or deduplication	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Delete source

DELETE /api/v1/projects/{project_id}/environments/{environment_id}/sources/{source_id}

Deletes it with its connections; its URL stops accepting requests. Stored events stay until retention removes them.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
source_id required	path	string	src_ ID

Responses

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

Get source

GET /api/v1/projects/{project_id}/environments/{environment_id}/sources/{source_id}

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
source_id required	path	string	src_ ID

Responses

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

Update source

PATCH /api/v1/projects/{project_id}/environments/{environment_id}/sources/{source_id}

Its URL never changes.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
source_id required	path	string	src_ ID

Request body

JSON, UpdateSource.

Field	Type	Description
deduplication	Deduplication | null
handshake	Handshake | null	Defaults to none.
methods	Method[] | null
name	string | null
response	SourceResponse | null
search_fields	string[] | null	Replaces the list; events already stored keep what they had.
verification	Verification | null

Responses

Status	Description	Body
200	Updated	Source
401	No API key, or it is invalid or revoked	Problem
404	No such source, or no access	Problem
422	Invalid name, methods, response, verification or deduplication	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

List source secrets

GET /api/v1/projects/{project_id}/environments/{environment_id}/sources/{source_id}/secrets

Newest first, expired ones too.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
source_id required	path	string	src_ ID

Responses

Status	Description	Body
200	Newest first, without their values	SourceSecret[]
401	No API key, or it is invalid or revoked	Problem
404	No such source, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Add source secret

POST /api/v1/projects/{project_id}/environments/{environment_id}/sources/{source_id}/secrets

Adds the current secret. The one before it keeps verifying for overlap_seconds; older ones stop now.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
source_id required	path	string	src_ ID

Request body

JSON, AddSourceSecret.

Field	Type	Description
overlap_seconds	integer (int32) | null	How long the previous secret keeps working, 0 to 2592000 seconds; a day when left out.
value required	string	The secret as the provider shows it, such as Stripe's whsec_....

Responses

Status	Description	Body
201	Stored; its value is not returned	SourceSecret
401	No API key, or it is invalid or revoked	Problem
404	No such source, or no access	Problem
422	Invalid value or overlap	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The API has no MASTER_KEYS to seal it with	Problem

Delete source secret

DELETE /api/v1/projects/{project_id}/environments/{environment_id}/sources/{source_id}/secrets/{secret_id}

It stops verifying now, e.g. to end an overlap early.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
source_id required	path	string	src_ ID
secret_id required	path	string	sec_ ID

Responses

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

Send test event

POST /api/v1/projects/{project_id}/environments/{environment_id}/sources/{source_id}/test-events

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
source_id required	path	string	src_ ID

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	Stored, and routed unless it was held	TestEvent
401	No API key, or it is invalid or revoked	Problem
404	No such source, or no access	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