Postscript Webhooks API
Create, read, update and delete webhook subscriptions, fetch the Postscript-Signature signing token, retrieve example event payloads and trigger test deliveries.
OpenAPI Specification
openapi: 3.1.0
info:
title: Postscript Webhooks API
description: The Postscript Partner API (v2) lets partners and Shopify shops manage SMS subscribers, send custom events
into Flows, send transactional and conversational messages, read opt-in keywords, configure webhook subscriptions, and
run TCPA compliance operations (unsubscribe, redact). Harvested verbatim from the per-operation OpenAPI definitions published
on https://developers.postscript.io/reference.
version: '2.0'
contact:
name: Postscript Developer Support
email: developersupport@postscript.io
url: https://developers.postscript.io
termsOfService: https://postscript.io/api-terms-of-service
servers:
- url: https://api.postscript.io
security:
- sec0: []
tags:
- name: Webhooks
description: Create, read, update and delete webhook subscriptions; fetch the signing token, sample payloads and test deliveries.
paths:
/api/v2/webhooks:
post:
summary: Create Webhook Subscription
description: ''
operationId: create-webhook-subscription
parameters:
- name: X-Postscript-Shop-Token
in: header
description: Shop API Token. **Required for partners**. This header should be used only by partners. Shops should
include their API token in the *Authorization* header.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- callback_url
- event
properties:
callback_url:
type: string
description: Destination URL for webhook deliveries (HTTPS only).
event:
type: string
description: Webhook subscription event type.
default: shop.test
enum:
- shop.test
- shop.incoming_message
- shop.subscriber.opt_in
- shop.subscriber.opt_out
- shop.shop.email_collected
headers:
type: object
description: Custom key:value pairs to be sent as headers in every callback.
properties: {}
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"callback_url\": \"http://example.com\",\n \"created_at\": \"2019-08-24T14:15:22Z\",\n \"\
event\": \"shop.test\",\n \"headers\": {},\n \"id\": \"a47606a1-5b39-4a81-9480-c2cb738ff675\",\n \"\
updated_at\": \"2019-08-24T14:15:22Z\",\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Webhooks
get:
summary: List Webhook Subscriptions
description: ''
operationId: list-webhook-subscriptions
parameters:
- name: X-Postscript-Shop-Token
in: header
description: Shop API Token. **Required for partners**. This header should be used only by partners. Shops should
include their API token in the *Authorization* header.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"webhook_subscriptions\": [\n {\n \"callback_url\": \"http://example.com\",\n \
\ \"created_at\": \"2019-08-24T14:15:22Z\",\n \"event\": \"shop.test\",\n \"headers\": {},\n\
\ \"id\": \"a47606a1-5b39-4a81-9480-c2cb738ff675\",\n \"updated_at\": \"2019-08-24T14:15:22Z\"\
,\n }\n ]\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Webhooks
/api/v2/webhooks/{id}:
delete:
summary: Delete Webhook Subscription
description: ''
operationId: delete-webhook-subscription
parameters:
- name: id
in: path
description: The ID of the webhook subscription to delete.
schema:
type: string
required: true
- name: X-Postscript-Shop-Token
in: header
description: Shop API Token. **Required for partners**. This header should be used only by partners. Shops should
include their API token in the *Authorization* header.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Webhooks
get:
summary: Get Webhook Subscription
description: ''
operationId: get-webhook-subscription
parameters:
- name: id
in: path
description: ID of the webhook subscription to fetch.
schema:
type: string
required: true
- name: X-Postscript-Shop-Token
in: header
description: Shop API Token. **Required for partners**. This header should be used only by partners. Shops should
include their API token in the *Authorization* header.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"callback_url\": \"http://example.com\",\n \"created_at\": \"2019-08-24T14:15:22Z\",\n \"\
event\": \"shop.test\",\n \"headers\": {},\n \"id\": \"a47606a1-5b39-4a81-9480-c2cb738ff675\",\n \"\
updated_at\": \"2019-08-24T14:15:22Z\",\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Webhooks
patch:
summary: Update Webhook Subscription
description: ''
operationId: update-webhook-subscription
parameters:
- name: id
in: path
description: ID of the webhook subscription to update.
schema:
type: string
required: true
- name: X-Postscript-Shop-Token
in: header
description: Shop API Token. **Required for partners**. This header should be used only by partners. Shops should
include their API token in the *Authorization* header.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
callback_url:
type: string
description: Destination URL for webhook deliveries (HTTPS only).
headers:
type: object
description: Custom key:value pairs to be sent as headers in every callback.
properties: {}
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"callback_url\": \"http://example.com\",\n \"created_at\": \"2019-08-24T14:15:22Z\",\n \"\
event\": \"shop.test\",\n \"headers\": {},\n \"id\": \"a47606a1-5b39-4a81-9480-c2cb738ff675\",\n \"\
updated_at\": \"2019-08-24T14:15:22Z\",\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Webhooks
/api/v2/webhooks/example:
get:
summary: Example Event
description: ''
operationId: example-event
parameters:
- name: event
in: query
description: Webhook subscription `event` type.
required: true
schema:
type: string
enum:
- shop.test
- shop.incoming_message
- shop.subscriber.opt_in
- shop.subscriber.opt_out
- shop.email_collected
default: shop.test
- name: X-Postscript-Shop-Token
in: header
description: Shop API Token. **Required for partners**. This header should be used only by partners. Shops should
include their API token in the *Authorization* header.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"webhook_id\": \"89066f0a-eb36-4ed8-b98c-606e6dcac715\",\n \"resource_type\": \"shop\",\n\
\ \"resource_id\": \"shop_1234567abcd\",\n \"event_time\": \"2021-11-04T21:52:41.025455\",\n \"event\"\
: \"shop.incoming_message\",\n \"event_data\": {\n \"id\": \"im_1b2a005a386281c9\",\n \"subscriber_id\"\
: \"s_1234567abcd\",\n \"shop_id\": \"shop_1234567abcd\",\n \"is_opt_out\": false,\n \"shopify_customer_id\"\
: null,\n \"from_number\": \"+15555555555\",\n \"created_at\": \"2021-11-04T21:52:41.025455\",\n\
\ \"body\": \"Hello, world\"\n }\n}"
schema:
type: object
properties:
webhook_id:
type: string
example: 89066f0a-eb36-4ed8-b98c-606e6dcac715
resource_type:
type: string
example: shop
resource_id:
type: string
example: shop_1234567abcd
event_time:
type: string
example: '2021-11-04T21:52:41.025455'
event:
type: string
example: shop.incoming_message
event_data:
type: object
properties:
id:
type: string
example: im_1b2a005a386281c9
subscriber_id:
type: string
example: s_1234567abcd
shop_id:
type: string
example: shop_1234567abcd
is_opt_out:
type: boolean
example: false
default: true
shopify_customer_id: {}
from_number:
type: string
example: '+15555555555'
created_at:
type: string
example: '2021-11-04T21:52:41.025455'
body:
type: string
example: Hello, world
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Webhooks
/api/v2/webhooks/test:
post:
summary: Test Shop Webhook
description: ''
operationId: test-shop-webhook
parameters:
- name: X-Postscript-Shop-Token
in: header
description: Shop API Token. **Required for partners**. This header should be used *only* by partners. Shops should
include their API token in the *Authorization* header.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- event
properties:
event:
type: string
description: Webhook subscription event type.
default: shop.test
enum:
- shop.test
- shop.incoming_message
- shop.subscriber.opt_in
- shop.subscriber.opt_out
- shop.email_collected
responses:
'202':
description: '202'
content:
application/json:
examples:
Result:
value: "{\n \"message\": \"OK\"\n}"
schema:
type: object
properties:
message:
type: string
example: OK
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "{\n \"errors\": [\n {\n \"ctx\": {},\n \"log\": [\n \"string\"\n ],\n\
\ \"msg\": \"string\",\n \"type\": \"string\"\n }\n ]\n}"
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
ctx:
type: object
properties: {}
log:
type: array
items:
type: string
example: string
msg:
type: string
example: string
type:
type: string
example: string
deprecated: false
tags:
- Webhooks
/api/v2/webhooks/token:
get:
summary: Get Webhook Signing Token
description: ''
operationId: get-webhook-signing-token
parameters:
- name: X-Postscript-Shop-Token
in: header
description: Shop API Token. **Required for partners**. This header should be used only by partners. Shops should
include their API token in the *Authorization* header.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"token\": \"string\"\n}"
schema:
type: object
properties:
token:
type: string
example: string
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Webhooks
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: Authorization
x-bearer-format: bearer