Webhook endpoints
What each event carries and how to verify a request: the webhooks guide.
GET /api/v1/webhooks
Your webhooks, newest first, and the events one can subscribe to.
- Scope
postory:read - Limit class
READ - Success
200
Example
curl https://postory.io/api/v1/webhooks \
-H "Authorization: Bearer $POSTORY_API_KEY"{"available_events": ["<available_events>"], "max_webhooks": 0}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
422A request parameter is not valid
429Rate limit spent; see Retry-After
POST /api/v1/webhooks
Create a webhook (10 at most). The answer carries the whsec_ signing secret once. reply.received and import.completed need a key with Read your account data; a private or local URL is 403 private_address. Idempotency-Key replays the first answer for 24 hours, so a retry makes no second webhook.
- Scope
postory:read - Limit class
WRITE - Success
201
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | Any unique string (1-255 characters). The first answer for this key is replayed for 24 hours ( |
Request body
| Field | Type | Description |
|---|---|---|
connection_ids | string[] | Only these accounts' post and reply events (up to 50). Omitted: every account. Up to 50 items |
eventsrequired | "post.published" | "post.failed" | "post.scheduled" | "reply.received" | "import.completed"[] | The events to send, 1 to 10. |
name | string | Your label for it, up to 80 characters. Up to 80 characters |
urlrequired | string | Where Postory POSTs each event: an |
Example
curl https://postory.io/api/v1/webhooks \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Idempotency-Key: <unique-key>" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/postory-webhook",
"events": ["post.published", "post.failed"]
}'{"secret": "<secret>"}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A request parameter is not valid
429Rate limit spent; see Retry-After
GET /api/v1/webhooks/{webhook_id}
One webhook (never its secret).
- Scope
postory:read - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string | Up to 36 characters |
Example
curl "https://postory.io/api/v1/webhooks/<webhook_id>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"connection_ids": ["<connection_ids>"],
"disabled_reason": "<disabled_reason>",
"events": ["<events>"],
"id": "<id>",
"is_enabled": true,
"name": "<name>",
"secret_hint": "<secret_hint>",
"url": "<url>"
}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
422A request parameter is not valid
429Rate limit spent; see Retry-After
PATCH /api/v1/webhooks/{webhook_id}
Change the URL, events, name or accounts, or turn it off (is_enabled: false) and on.
- Scope
postory:read - Limit class
WRITE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string | Up to 36 characters |
Request body
| Field | Type | Description |
|---|---|---|
connection_ids | string[] | REPLACES the accounts whose events are sent (up to 50); |
events | "post.published" | "post.failed" | "post.scheduled" | "reply.received" | "import.completed"[] | REPLACES the events. The events to send, 1 to 10. |
is_enabled | boolean |
|
name | string | Your label for it, up to 80 characters. Up to 80 characters |
url | string | Where Postory POSTs each event: an |
Example
curl -X PATCH "https://postory.io/api/v1/webhooks/<webhook_id>" \
-H "Authorization: Bearer $POSTORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"connection_ids": ["<connection_ids>"]}'{
"connection_ids": ["<connection_ids>"],
"disabled_reason": "<disabled_reason>",
"events": ["<events>"],
"id": "<id>",
"is_enabled": true,
"name": "<name>",
"secret_hint": "<secret_hint>",
"url": "<url>"
}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A request parameter is not valid
429Rate limit spent; see Retry-After
DELETE /api/v1/webhooks/{webhook_id}
Delete a webhook and its delivery log.
- Scope
postory:read - Limit class
WRITE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string | Up to 36 characters |
Example
curl -X DELETE "https://postory.io/api/v1/webhooks/<webhook_id>" \
-H "Authorization: Bearer $POSTORY_API_KEY"{"deleted": true, "id": "<id>"}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
422A request parameter is not valid
429Rate limit spent; see Retry-After
GET /api/v1/webhooks/{webhook_id}/deliveries
The newest deliveries: event, status, attempts, the endpoint's status code and when the next retry is due.
- Scope
postory:read - Limit class
READ - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string | Up to 36 characters |
limit | query | integer | How many deliveries, 1-100 (default 50). Default: 50 · From 1 to 100 |
Example
curl "https://postory.io/api/v1/webhooks/<webhook_id>/deliveries" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"deliveries": [
{
"attempt": 0,
"created_at": "<created_at>",
"delivered_at": "<delivered_at>",
"event_id": "<event_id>",
"event_type": "<event_type>",
"id": "<id>",
"last_error": "<last_error>",
"last_status_code": 0,
"next_attempt_at": "<next_attempt_at>",
"response_ms": 0,
"status": "<status>"
}
],
"webhook_id": "<webhook_id>"
}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
422A request parameter is not valid
429Rate limit spent; see Retry-After
POST /api/v1/webhooks/{webhook_id}/rotate-secret
A new signing secret, used from the next delivery; the old one stops.
- Scope
postory:read - Limit class
WRITE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string | Up to 36 characters |
Example
curl -X POST "https://postory.io/api/v1/webhooks/<webhook_id>/rotate-secret" \
-H "Authorization: Bearer $POSTORY_API_KEY"{"secret": "<secret>"}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
422A request parameter is not valid
429Rate limit spent; see Retry-After
POST /api/v1/webhooks/{webhook_id}/test
Send a signed webhook.test now; answers the delivery with the endpoint's status code (a failed test is retried like any delivery).
- Scope
postory:read - Limit class
WRITE - Success
200
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhook_idrequired | path | string | Up to 36 characters |
Example
curl -X POST "https://postory.io/api/v1/webhooks/<webhook_id>/test" \
-H "Authorization: Bearer $POSTORY_API_KEY"{
"attempt": 0,
"created_at": "<created_at>",
"delivered_at": "<delivered_at>",
"event_id": "<event_id>",
"event_type": "<event_type>",
"id": "<id>",
"last_error": "<last_error>",
"last_status_code": 0,
"next_attempt_at": "<next_attempt_at>",
"response_ms": 0,
"status": "<status>"
}Other responses
401No API key, or an invalid or revoked one
403The key lacks the scope, or access is paused
404Not found, or not this user's
409The state does not allow it now (already scheduled, changed, needs a choice…); branch on
code422A request parameter is not valid
429Rate limit spent; see Retry-After