Webhook inboxes: capture and inspect HTTP callbacks

What a webhook inbox does

A webhook inbox is a temporary URL that records every request sent to it. Use it to see exactly what a payment provider, Git host, form service or your own code sends before you write a handler. The inbox answers each sender with 200 and stores the method, path, headers, query parameters and body for you to read.

Create an inbox

POST /api/inboxes takes no body. Optional query parameters set visibility, ttlSeconds and persistent; see Lifetimes and renewal. The response includes webhookUrl, the inspectionToken for reading and deleting, and, for private inboxes, the accessToken that senders need.

curl -X POST 'https://socket.help/api/inboxes?visibility=public&ttlSeconds=1800'

# 201 Created
{
  "id": "INBOX_ID",
  "inspectionToken": "INSPECTION_TOKEN",
  "expiresAt": "2026-10-27T12:30:00.000Z",
  "visibility": "public",
  "accessVersion": "ACCESS_VERSION",
  "webhookUrl": "https://socket.help/hooks/INBOX_ID"
}

Send requests to the webhook URL

The webhook URL accepts GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS, with a body on any method up to 100 KiB. Query strings are captured; additional path segments after the inbox ID are not accepted.

A successful capture returns 200 with {"received":true,"requestId":"..."} and an X-Webhook-Request-Id header. HEAD returns 200 with no body. The response status and body are fixed; an inbox cannot be configured to answer differently. Use a mock API for that.

Private inboxes accept a request only with the access token in X-Access-Token or Authorization: Bearer. Without it the sender gets 404 and nothing is stored. Workspace credentials with resources:write can also send to their own private inboxes.

curl -X POST 'https://socket.help/hooks/INBOX_ID?source=test' \
  -H "X-Access-Token: $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"type":"invoice.paid","id":"evt_test_1"}'

# 200 OK
# X-Webhook-Request-Id: CAPTURE_ID
{"received":true,"requestId":"CAPTURE_ID"}

Read captured requests

GET /api/inboxes/{id}/requests returns captures in arrival order. Each record has id, method, path, headers, query, body, bodyEncoding, bodySize and timestamp. Bodies that are valid UTF-8 are stored as text; other bodies are stored as Base64 with bodyEncoding set to base64.

Header names that contain authorization, cookie, token, api key, secret or password are stored as [REDACTED]. Bodies and query values are kept as sent, so use test data.

For polling, the response has an ETag. Send it back in If-None-Match and you get 304 until a new request arrives. The response also carries X-Resource-Visibility, X-Access-Version and X-Resource-Expires-At headers.

curl -i https://socket.help/api/inboxes/INBOX_ID/requests \
  -H "Authorization: Bearer $INSPECTION_TOKEN" \
  -H 'If-None-Match: "ETAG_FROM_LAST_RESPONSE"'

Inbox details and deletion

GET /api/inboxes/{id} returns id, visibility, accessVersion, expiresAt, requestCount and storedBytes, plus createdAt, persistent, requestLimit and byteLimit. DELETE /api/inboxes/{id} removes the inbox and its history immediately and returns 204.

Use the inspection token for anonymous inboxes. Inboxes created with an API key are managed with workspace access; send the key instead.

Limits

Anonymous inboxes hold up to 100 requests or 1 MiB of captured data; account inboxes hold up to 1,000 requests or 10 MiB. When an inbox is full, new captures get 429 and existing history stays readable. Each inbox accepts up to 120 requests per minute.