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 to true 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 URL
alias 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) or token_id)
order_direction - order direction (asc (default) or desc)

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¶

See POST /token

Response¶

See POST /token

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¶

{"password": "hunter2", "old_password": "hunter1"}

Response¶

See POST /token

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¶

{"alias": "my-webhook"}

Response¶

See POST /token

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¶

{ "enabled": true}

Get token¶

Can require authentication.

GET /token/:token_id

Response¶

See POST /token

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 - either newest or oldest (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, format yyyy-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 word foobar
content:foobar - returns requests or emails with body contents containing the word foobar
method:GET - returns all requests with method GET
headers.user-agent:"Paw/3.3.5 (Macintosh; OS X/11.6.2) GCDHTTPRequest" - search value of user-agent header
query.action:create - returns requests that have the query string action set to create.
_exists_:query.action - returns requests where the action query is set to
type:web / type:email - returns either Web requests or emails
type:web AND method:POST - AND query
method: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

API Endpoints:Tokens (URLs & Email Addresses)¶

Tokens¶

Create token¶

Request¶

Example 1: JSON¶

Example 2: Creating with Python 3¶

Response¶

Get tokens¶

Request¶

Query string parameters¶

Response¶

Update token¶

Request¶

Response¶

Set password (Pro)¶

Request¶

Response¶

Set alias (Pro)¶

Request¶

Response¶

Toggle CORS¶

Response¶

Get token¶

Response¶

Delete token¶

Response¶

Requests¶

Capture request¶

Request¶

Response¶

Get requests¶

Query string parameters¶

Query string search examples¶

Response¶

Get single/latest request¶

Response¶

Get raw request content¶

Download request file¶

Delete request¶

Response¶

API Endpoints:
Tokens (URLs & Email Addresses)¶