API Endpoints:
Tokens (URLs & Email Addresses)¶
Tokens¶
A token is a container for incoming requests and emails, and corresponds to a Webhook.site URL or Email. A token ID is a 36 character UUID consisting of hexadecimal characters and dashes.
Simply, the token ID is the part after https://webhook.site/
in the URL, or before @email.webhook.site
in the email address.
Create token¶
POST /token
After creating a token, the URL at https://webhook.site/{token.uuid}
becomes accessible, and emails can be sent to {token.uuid}@email.webhook.site
.
Rate limit: 10 per minute (free); 60 per minute (Pro and Enterprise)
default_*
parameters sets the response of the URL.timeout
waits an amount of seconds before returning the response (intended for testing timeouts)expiry
set totrue
will cause the token to automatically be deleted within 7 days of no activity, even if creating the token as a Pro user. If you're using tokens for automated testing, for example, you can enable this to avoid filling up your user profile.cors
set to true will add CORS headers to the request so browsers will send cross-domain requests to the URLalias
allows setting the alias of the token.actions
specifies if Custom Actions are enabled and executed on every request/email (true), or disabled (false.)clone_from
specifies a token UUID (or alias) that will act as a template for the new token. When specified, settingssuch as default content, timeout, password as well as Custom Actions are copied to the new token.group_id
specifies which group ID the token should be added to.
Request¶
Example 1: JSON¶
{
"default_status": 200,
"default_content": "Hello world!",
"default_content_type": "text/html",
"timeout": 0,
"cors": false,
"expiry": true,
"alias": "my-webhook",
"actions": true
}
Example 2: Creating with Python 3¶
Requires the requests
module, which can be installed using pip install requests
. You'll also need to replace the API key. Create an API key here.
import requests
json = {
"default_status": 200,
"default_content": "Hello world!",
"default_content_type": "text/html",
}
headers = {
"api-key": "00000000-0000-0000-0000-000000000000"
}
r = requests.post('https://webhook.site/token', json=json, headers=headers)
print('URL Created: https://webhook.site/' + r.json()['uuid'])
Response¶
200 OK
{
"redirect": false,
"alias": null,
"timeout": 0,
"premium": true,
"uuid": "9981f9f4-657a-4ebf-be7c-1915bedd4775",
"ip": "127.0.0.1",
"user_agent": "Paw\/3.1.8 (Macintosh; OS X\/10.14.6) GCDHTTPRequest",
"default_content": "Hello world!",
"default_status": 200,
"default_content_type": "text\/plain",
"premium_expires_at": "2019-10-22 10:52:20",
"created_at": "2019-09-22 10:52:20",
"updated_at": "2019-09-22 10:52:20"
}
Note about expiry: If there's no incoming requests for about a week, and the token is not upgraded to premium, the token is automatically deleted along with any other data.
Get tokens¶
- Requires authentication.
Request¶
GET /token
Returns a list of all Tokens associated with an account.
Query string parameters¶
per_page
- amount of requests returned, defaults to 50 (max 100)page
- page number to retrieve (default 1)order_by
- which field to order tokens by (created_at
(default) ortoken_id
)order_direction
- order direction (asc
(default) ordesc
)
Response¶
{
"current_page": 1,
"data": [
{
"uuid": "44fb1548-cd1f-4928-880c-cce094e5e179",
"redirect": false,
"alias": null,
"actions": true,
"cors": false,
"expiry": false,
"timeout": 0,
"premium": true,
"user_id": null,
"password": true,
"ip": "127.0.0.1",
"user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit\/605.1.15 (KHTML, like Gecko) Version\/14.0.3 Safari\/605.1.15",
"default_content": "",
"default_status": 200,
"default_content_type": "text\/plain",
"premium_expires_at": null,
"created_at": "2021-08-11 18:34:44",
"updated_at": "2021-08-11 18:34:44",
"require_auth": true,
"latest_request_id": "ea5f5920-0398-465c-8f9c-8074f0d805a4",
"latest_request_at": "2021-08-12 19:56:50",
"category_id": null,
"requests": 1
},
...
],
"first_page_url": "https:\/\/webhook.site\/token?page=1",
"from": 1,
"last_page": 1,
"last_page_url": "https:\/\/webhook.site\/token?page=1",
"next_page_url": null,
"path": "https:\/\/webhook.site\/token",
"per_page": 50,
"prev_page_url": null,
"to": 2,
"total": 2
}
Update token¶
- Can require authentication.
PUT /token/:token_id
Request¶
Response¶
Set password (Pro)¶
- Can require authentication.
- Requires user with Pro upgrade.
PUT /token/:token_id/password
Sets a password to view the requests of a token.
Request¶
Response¶
Set alias (Pro)¶
- Can require authentication.
- Requires user with Pro upgrade.
PUT /token/:token_id/alias
Sets the alias for the token, which makes the token available at https://webhook.site/<alias>
or <alias>@email.webhook.site
in addition to its 36 character UUID.
Rules for alias format: Length between 3-32 characters. Allowed characters: A-Z, a-z and - (dash.)
Request¶
Response¶
Toggle CORS¶
Attaches CORS headers to the response of the Token, allowing browsers to request it from all domains.
PUT /token/:token_id/cors/toggle
Response¶
Get token¶
- Can require authentication.
GET /token/:token_id
Response¶
Delete token¶
- Can require authentication.
DELETE /token/:token_id
Response¶
204 No Content
Requests¶
Capture request¶
(any method) /:tokenId
(any method) /:tokenId/:statusCode
(any method) /:tokenId/(anything)
If statusCode
is valid, that HTTP status will be used in the response (instead of the default.)
Instead of tokenId
, an alias can also be supplied.
Request¶
(Anything.)
Response¶
(The default response of the Token.)
Get requests¶
- Can require authentication.
GET /token/:token_id/requests
Lists all request sent to a token.
Rate limit: 120 requests per minute.
Query string parameters¶
sorting
- eithernewest
oroldest
(default)per_page
- amount of requests returned, defaults to 50 (max 100)page
- page number to retrieve (default 1)date_from
,date_to
- filter requests by date, formatyyyy-MM-dd HH:mm:ss
query
- filter requests by a query string search (see below for examples)
Query string search examples¶
You can filter requests by a query string syntax:
foobar
- returns requests or emails with body contents containing the wordfoobar
content:foobar
- returns requests or emails with body contents containing the wordfoobar
method:GET
- returns all requests with method GETheaders.user-agent:"Paw/3.3.5 (Macintosh; OS X/11.6.2) GCDHTTPRequest"
- search value of user-agent headerquery.action:create
- returns requests that have the query stringaction
set tocreate
._exists_:query.action
- returns requests where the action query is set totype:web
/type:email
- returns either Web requests or emailstype:web AND method:POST
- AND querymethod:PUT OR method:POST
- OR query(method:PUT) AND (content:example OR content:test) AND NOT (content:foobar)
created_at:["2022-01-01 00:00:00" TO "2022-12-31 00:00:00"]
- date range query
Response¶
{
"data": [
{
"uuid": "a2a6a4ae-4130-4063-953a-84fa29d81d43",
"token_id": "a94a7294-c4aa-4074-ab77-c4cf86fd53b1",
"ip": "127.0.0.1",
"hostname": "webhook.site",
"method": "POST",
"user_agent": "Paw\/3.1.8 (Macintosh; OS X\/10.14.6) GCDHTTPRequest",
"content": "{\"first_name\":\"Arch\",\"last_name\":\"Weber\"}",
"query": {
"action": "create"
},
"request": {
"status": "example"
},
"files": {
"file": {
"id": "98bf4c25-58ab-4c5d-ba91-fb6f709ea78d",
"filename": "example.png",
"size": 420915,
"content_type": "image/png"
}
},
"headers": {
"content-length": [
"271"
],
"user-agent": [
"Paw\/3.1.8 (Macintosh; OS X\/10.14.6) GCDHTTPRequest"
]
},
"url": "https:\/\/webhook.site\/a94a7294-c4aa-4074-ab77-c4cf86fd53b1\/201?",
"created_at": "2019-10-03 19:06:35",
"updated_at": "2019-10-03 19:06:35",
"custom_action_output": []
}
],
"total": 1,
"per_page": 50,
"current_page": 1,
"is_last_page": true,
"from": 1,
"to": 1
}
Get single/latest request¶
- Can require authentication.
GET /token/:token_id/request/:request_id
GET /token/:token_id/request/latest
- retrieves the latest request sent to the URL
Response¶
{
"uuid": "a2a6a4ae-4130-4063-953a-84fa29d81d43",
"token_id": "a94a7294-c4aa-4074-ab77-c4cf86fd53b1",
"ip": "127.0.0.1",
"hostname": "webhook.site",
"method": "POST",
"user_agent": "Paw\/3.1.8 (Macintosh; OS X\/10.14.6) GCDHTTPRequest",
"content": "{\"first_name\":\"Arch\",\"last_name\":\"Weber\"}",
"query": {
"action": "create"
},
"headers": {
"content-length": [
"271"
],
"user-agent": [
"Paw\/3.1.8 (Macintosh; OS X\/10.14.6) GCDHTTPRequest"
]
},
"files": {
"foo": {
"id": "65d6e0ce-a840-47bc-b6b6-ff1ff38c34ca",
"filename": "example.json",
"size": 5132873,
"content_type": "text/plain"
}
},
"url": "https:\/\/webhook.site\/a94a7294-c4aa-4074-ab77-c4cf86fd53b1\/201?",
"created_at": "2019-10-03 19:06:35",
"updated_at": "2019-10-03 19:06:35"
}
Get raw request content¶
- Can require authentication.
GET /token/:token_id/request/:request_id/raw
GET /token/:token_id/request/latest/raw
- retrieves the latest request sent to the URL
Returns the request as a response (body, content-type.)
Download request file¶
- Can require authentication.
GET /token/:tokenId/request/:requestId/download/:fileId
Files that are included in a request or as email attachments are available to download using this endpoint.
Delete request¶
- Can require authentication.
DELETE /token/:token_id/request/:request_id
DELETE /token/:token_id/request
Deletes a request.
If no request_id
, all requests related to the token will be deleted.
Response¶
204 No Content