pricklymails-com Webhooks API
Webhook endpoints that receive your verification events.
Webhook endpoints that receive your verification events.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/pricklymails-com:pricklymails-com-webhooks-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Pricklymails Com Webhooks API
version: 0.9.0
contact:
email: support@pricklymails.com
license:
name: Proprietary
description: 'Operations tagged webhooks across 2 of this provider''s published API definitions: pricklymails-com-openapi.json, pricklymails-com-openapi.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Webhooks
description: Webhook endpoints that receive your verification events.
paths:
/api/webhooks:
get:
tags:
- Webhooks
summary: Lists every webhook endpoint of the authenticated account
operationId: list_webhooks
responses:
'200':
description: The caller's webhook endpoints.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WebhookResponse'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: The key or agent token lacks the `webhooks:read` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
post:
tags:
- Webhooks
summary: Creates a webhook endpoint for the authenticated account and returns its…
description: 'The secret is returned only by this call; every later read returns metadata only. The URL must be an HTTPS address of at most 2048 characters that does not point to a private or loopback address. `events` is required and must list at least one event, such as `job.completed` or `job.failed`. The number of active endpoints is capped by the account''s plan.
Each delivery is a JSON `POST` carrying an `X-PricklyMails-Event` header with the event name and an `X-PricklyMails-Signature` header of the form `t=,v1=`. The signature is the lowercase hex HMAC-SHA256 of `.`, keyed with the `secret` string exactly as returned here.'
operationId: create_webhook
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookRequest'
required: true
responses:
'201':
description: Endpoint created; `secret` is shown once.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookResponse'
'400':
description: Invalid url, events, or empty events list.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: Plan webhook-endpoint limit reached, or the key or agent token lacks the `webhooks:create` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
/api/webhooks/{uuid}:
get:
tags:
- Webhooks
summary: Returns one webhook endpoint of the authenticated account
operationId: get_webhook
parameters:
- name: uuid
in: path
description: Public UUID of the webhook endpoint.
required: true
schema:
type: string
responses:
'200':
description: The requested webhook endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookResponse'
'400':
description: Malformed uuid.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: The key or agent token lacks the `webhooks:read` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'404':
description: No endpoint with that uuid owned by the caller.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
delete:
tags:
- Webhooks
summary: Deletes a webhook endpoint
description: 'Idempotent: deleting an endpoint that no longer exists still returns `204`.'
operationId: delete_webhook
parameters:
- name: uuid
in: path
description: Public UUID of the webhook endpoint.
required: true
schema:
type: string
responses:
'204':
description: Endpoint deleted (idempotent on repeat calls).
'400':
description: Malformed uuid.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: The key or agent token lacks the `webhooks:delete` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
patch:
tags:
- Webhooks
summary: Updates the URL, subscribed events, description or status of a webhook endpoint
description: Omitted fields keep their current values. `status` accepts `"active"` or `"paused"`; a paused endpoint receives no deliveries.
operationId: update_webhook
parameters:
- name: uuid
in: path
description: Public UUID of the webhook endpoint.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWebhookRequest'
required: true
responses:
'200':
description: The updated webhook endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookResponse'
'400':
description: Invalid url, events, empty events list, or status.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: The key or agent token lacks the `webhooks:update` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'404':
description: No endpoint with that uuid owned by the caller.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
/api/webhooks/{uuid}/deliveries:
get:
tags:
- Webhooks
summary: Returns the delivery attempts made to one endpoint, newest first, paginated
description: Test attempts from `POST /api/webhooks/{uuid}/test` are included and flagged with `is_test`. A `limit` outside 1 to 96 is clamped to that range.
operationId: list_webhook_deliveries
parameters:
- name: uuid
in: path
description: Public UUID of the webhook endpoint.
required: true
schema:
type: string
- name: limit
in: query
description: Number of entries to return (default 20, cap 96).
required: false
schema:
type: integer
format: int64
- name: offset
in: query
description: Number of entries to skip (default 0).
required: false
schema:
type: integer
format: int64
responses:
'200':
description: Paginated delivery history, newest first.
content:
application/json:
schema:
$ref: '#/components/schemas/ListWebhookDeliveriesResponse'
'400':
description: Malformed uuid.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: The key or agent token lacks the `webhooks:read` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'404':
description: No endpoint with that uuid owned by the caller.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
/api/webhooks/{uuid}/test:
post:
tags:
- Webhooks
summary: Sends a signed test delivery to a webhook endpoint
description: 'Sends one signed sample delivery to the caller''s own endpoint, so they can verify their receiver and signature verification before any real job completes. The request is signed exactly like a real delivery (`X-PricklyMails-Signature`) and carries a `job.completed` sample payload with `test: true`. It does not change the endpoint''s delivery counters; the attempt is recorded with `is_test: true` in `GET /api/webhooks/{uuid}/deliveries`.'
operationId: test_webhook
parameters:
- name: uuid
in: path
description: Public UUID of the webhook endpoint.
required: true
schema:
type: string
responses:
'200':
description: The test-fire outcome.
content:
application/json:
schema:
$ref: '#/components/schemas/TestWebhookResponse'
'400':
description: Malformed uuid.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'401':
description: Missing or invalid API key, session token, or agent token.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: The key or agent token lacks the `webhooks:update` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'404':
description: No endpoint with that uuid owned by the caller.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
components:
schemas:
CreateWebhookRequest:
type: object
description: '`POST /api/webhooks` request body.'
required:
- url
- events
properties:
description:
type:
- string
- 'null'
description: Free-text description of the endpoint.
events:
type: array
items:
type: string
description: Events to subscribe to, for example `"job.completed"` or `"job.failed"`. At least one is required.
url:
type: string
description: HTTPS URL that receives event notifications (at most 2048 characters, no private or loopback address).
WebhookResponse:
type: object
description: Metadata of a webhook endpoint, returned when listing, reading or updating endpoints.
required:
- uuid
- url
- events
- status
- total_deliveries
- successful_deliveries
- consecutive_failures
- created_at
properties:
consecutive_failures:
type: integer
format: int32
description: Number of failed deliveries in a row since the last success.
minimum: 0
created_at:
type: string
description: RFC 3339 creation timestamp.
description:
type:
- string
- 'null'
description: Description of the endpoint, omitted when none was set.
events:
type: array
items:
type: string
description: Events the endpoint is subscribed to.
last_delivery_at:
type:
- string
- 'null'
description: RFC 3339 timestamp of the last delivery, omitted when there was none.
status:
type: string
description: 'Status of the endpoint: `"active"`, `"paused"` or `"disabled"`.'
successful_deliveries:
type: integer
format: int64
description: Number of deliveries the endpoint acknowledged with a 2xx status.
minimum: 0
total_deliveries:
type: integer
format: int64
description: Number of deliveries attempted.
minimum: 0
url:
type: string
description: URL that receives the notifications.
uuid:
type: string
description: Public UUID of the endpoint.
ApiErrorBody:
type: object
description: 'Error envelope returned with every non-success status: `{ "error": { "code", "message" } }`.'
required:
- error
properties:
error:
$ref: '#/components/schemas/ApiErrorDetail'
description: Error detail.
ListWebhookDeliveriesResponse:
type: object
description: '`GET /api/webhooks/{uuid}/deliveries` response body.'
required:
- deliveries
- limit
- offset
properties:
deliveries:
type: array
items:
$ref: '#/components/schemas/WebhookDeliveryItem'
description: Delivery attempts, newest first.
limit:
type: integer
format: int64
description: Page size applied after clamping.
offset:
type: integer
format: int64
description: Offset applied.
WebhookDeliveryItem:
type: object
description: One delivery attempt listed by `GET /api/webhooks/{uuid}/deliveries`.
required:
- event
- job_uuid
- attempt_number
- is_test
- created_at
properties:
attempt_number:
type: integer
format: int32
description: Attempt number, starting at 1.
minimum: 0
created_at:
type: string
description: RFC 3339 timestamp of the attempt.
event:
type: string
description: Event that was delivered, for example `"job.completed"`.
is_test:
type: boolean
description: '`true` for an attempt made by `POST /api/webhooks/{uuid}/test`.'
job_uuid:
type: string
description: UUID of the job the event relates to (all zeros for a test attempt).
response_body:
type:
- string
- 'null'
description: Response body returned by the endpoint, omitted when there was none.
response_status:
type:
- integer
- 'null'
format: int32
description: HTTP status returned by the endpoint, omitted when the request failed before a response.
minimum: 0
UpdateWebhookRequest:
type: object
description: '`PATCH /api/webhooks/{uuid}` request body.'
properties:
description:
type:
- string
- 'null'
description: New description. Left unchanged when absent.
events:
type:
- array
- 'null'
items:
type: string
description: New list of subscribed events, with at least one entry. Left unchanged when absent.
status:
type:
- string
- 'null'
description: 'New status: `"active"` or `"paused"`. Left unchanged when absent.'
url:
type:
- string
- 'null'
description: New HTTPS URL. Left unchanged when absent.
ApiErrorDetail:
type: object
description: Detail of an error response.
required:
- code
properties:
code:
type: string
description: Stable key identifying the error (for example `"verify.invalid_uuid"`). Clients localize by this key.
message:
type:
- string
- 'null'
description: 'Present on most error kinds and equal to `code`; the API returns no localized text.
Absent for error kinds that carry no extra detail.'
TestWebhookResponse:
type: object
description: '`POST /api/webhooks/{uuid}/test` response body: the outcome of the single test-fire attempt.'
required:
- delivered
properties:
delivered:
type: boolean
description: '`true` when the endpoint answered with a 2xx status.'
error:
type:
- string
- 'null'
description: A transport error message, or a description of the non-2xx status, `None` on success.
status_code:
type:
- integer
- 'null'
format: int32
description: The HTTP status the endpoint returned, `None` on a transport-level failure.
minimum: 0
CreateWebhookResponse:
allOf:
- $ref: '#/components/schemas/WebhookResponse'
- type: object
required:
- secret
properties:
secret:
type: string
description: The signing secret, hex-encoded. It is returned only once, so store it securely.
description: '`POST /api/webhooks` response body.
Carries the endpoint metadata plus its signing secret.'
securitySchemes:
bearer_api_key:
type: http
scheme: bearer
description: A `pm_live_*` or `pm_test_*` API key.
jwt:
type: http
scheme: bearer
description: A short-lived token from `/api/auth/login`, or `/oauth/token` for an agent.
x-refined-from:
- pricklymails-com-openapi.json
- pricklymails-com-openapi.yaml