Docs menuWebhook endpoints

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.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Example

Request
curl https://postory.io/api/v1/webhooks \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{"available_events": ["<available_events>"], "max_webhooks": 0}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

422

A request parameter is not valid

429

Rate 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.

  • Scopepostory:read
  • Limit classWRITE
  • Success201

Parameters

NameInTypeDescription
Idempotency-Keyheaderstring

Any unique string (1-255 characters). The first answer for this key is replayed for 24 hours (Idempotent-Replayed: true) without running anything again; the same key with a different request is 409 idempotency_conflict.

Up to 255 characters

Request body

FieldTypeDescription
connection_idsstring[]

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. reply.received and import.completed need a key with the postory:data scope (Read your account data); otherwise scope_required.

1–10 items
namestring

Your label for it, up to 80 characters.

Up to 80 characters
urlrequiredstring

Where Postory POSTs each event: an https:// URL on a public address, no user name or password.

Up to 2000 characters

Example

Request
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"]
  }'
Response 201
{"secret": "<secret>"}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

409

The state does not allow it now (already scheduled, changed, needs a choice…); branch on code

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

GET /api/v1/webhooks/{webhook_id}

One webhook (never its secret).

  • Scopepostory:read
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
webhook_idrequiredpathstringUp to 36 characters

Example

Request
curl "https://postory.io/api/v1/webhooks/<webhook_id>" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "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

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

422

A request parameter is not valid

429

Rate 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.

  • Scopepostory:read
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
webhook_idrequiredpathstringUp to 36 characters

Request body

FieldTypeDescription
connection_idsstring[]

REPLACES the accounts whose events are sent (up to 50); [] = every account again.

Up to 50 items
events"post.published" | "post.failed" | "post.scheduled" | "reply.received" | "import.completed"[]

REPLACES the events. The events to send, 1 to 10. reply.received and import.completed need a key with the postory:data scope (Read your account data); otherwise scope_required.

1–10 items
is_enabledboolean

false turns the webhook off, true back on.

namestring

Your label for it, up to 80 characters.

Up to 80 characters
urlstring

Where Postory POSTs each event: an https:// URL on a public address, no user name or password.

Up to 2000 characters

Example

Request
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>"]}'
Response 200
{
  "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

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

409

The state does not allow it now (already scheduled, changed, needs a choice…); branch on code

422

A request parameter is not valid

429

Rate limit spent; see Retry-After

DELETE /api/v1/webhooks/{webhook_id}

Delete a webhook and its delivery log.

  • Scopepostory:read
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
webhook_idrequiredpathstringUp to 36 characters

Example

Request
curl -X DELETE "https://postory.io/api/v1/webhooks/<webhook_id>" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{"deleted": true, "id": "<id>"}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

422

A request parameter is not valid

429

Rate 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.

  • Scopepostory:read
  • Limit classREAD
  • Success200

Parameters

NameInTypeDescription
webhook_idrequiredpathstringUp to 36 characters
limitqueryinteger

How many deliveries, 1-100 (default 50).

Default: 50 · From 1 to 100

Example

Request
curl "https://postory.io/api/v1/webhooks/<webhook_id>/deliveries" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "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

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

422

A request parameter is not valid

429

Rate 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.

  • Scopepostory:read
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
webhook_idrequiredpathstringUp to 36 characters

Example

Request
curl -X POST "https://postory.io/api/v1/webhooks/<webhook_id>/rotate-secret" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{"secret": "<secret>"}

Other responses

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

422

A request parameter is not valid

429

Rate 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).

  • Scopepostory:read
  • Limit classWRITE
  • Success200

Parameters

NameInTypeDescription
webhook_idrequiredpathstringUp to 36 characters

Example

Request
curl -X POST "https://postory.io/api/v1/webhooks/<webhook_id>/test" \
  -H "Authorization: Bearer $POSTORY_API_KEY"
Response 200
{
  "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

401

No API key, or an invalid or revoked one

403

The key lacks the scope, or access is paused

404

Not found, or not this user's

409

The state does not allow it now (already scheduled, changed, needs a choice…); branch on code

422

A request parameter is not valid

429

Rate limit spent; see Retry-After