Subscriptions
Subscriptions tell Showpad which events you would like to receive notifications about. Each subscription is defined by its:
-
Type - Designates when webhooks are created and the content of the payload. For example,
shared-space-created
webhooks are sent whenever a shared space is created. The payload contains the details of the Shared Space and the user that created it. -
Endpoint- The destination where Showpad sends notifications for the specified event type.
There are two ways to manage your webhook subscriptions, via:
Online Platform
The following section describes how to manage your subscriptions on Showpad's Online Platform.
Subscribe to Events
Step | Description |
---|---|
1. | Sign in to Showpad's Online Platform and open the Admin Settings page. |
2. | Click on Webhooks in the Integrations section. If you don't see Webhooks in the Integrations section, contact your Showpad administrator. |
3. | Select the event that applies to your automation and click the + icon to add a webhook. Your middleware service should be mapped to the event using the identifiers in the Sample Body. To see a sample of what Showpad sends to your webhook URL, click Sample Body (in this example, we use the Sharing event). |
4. | Select an HTTP method (GET or POST ) to define how events are delivered to the webhook URL. |
5. | Add the URL that is used to accept webhook events and confirm. You can see how many requests an event has sent to a webhook by the number in the # requests column. |
6 | After successfully creating the webhook subscription, a signature key is displayed. The signature key can be used to ensure the authenticity and integrity of the webhook. For more information, see the webhook verification section. Note: The signature key is only visible once. Be sure that you copy and store it in a secure location. |
Additional Actions
You can monitor the responses from webhook requests by clicking on the View icon or delete the existing method by clicking on the Delete icon.
Action | Description |
---|---|
View Logs | Clicking the View icon displays Showpad's Webhook Log. The columns in the log display:
|
Delete Subscriptions | Clicking the Delete icon permanently removes the webhook and all of it's log history. A dialog is displayed to confirm the deletion. |
Webhook API
Subscribing to events via the Webhook API is done by sending requests to the subscriptions
endpoint at
https://{{subdomain}}.api.showpad.com/webhooks/v1...
using an
HTTP method.
Each subscription request has its own unique structure, depending on the endpoint. Please be sure to veryify that your requests conform to the structure defined in the API Specification.
You'll need to use your developer API token when making requests to these endpoints.
New Subscription
Creating a new webhook subscription and its signature key requires the following HTTP method and endpoint:
HTTP Method | Endpoint | Request body required? |
---|---|---|
POST | /subscriptions | Yes |
You can check out the API Specification for more information.
Example
# Create a new subscription
curl --request POST \
--url https://{{subdomain}}.api.showpad.com/webhooks/v1/subscriptions \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json' \
--data '{
"name": "my webhook",
"url": "https://my-domain.com/incoming-webhook",
"method": "GET",
"headers": [
{
"name": "Authorization",
"value": "Bearer xyz"
},
{
"name": "User-Agent",
"value": "Showpad-Webhook-Agent"
}
],
"types": [
"COURSE_COMPLETED"
]
}'
# Response a new subscription
{
"id":"01GVZ8663CJAREF2SJE5XQRX7W",
"url":"https://my-domain.com/incoming-webhook",
"name":"my webhook",
"createdAt":"2023-03-20T10:14:09.772Z",
"updatedAt":"2023-03-20T10:14:09.772Z",
"headers":[
{
"name": "Authorization",
"value": "Bearer xyz"
},
{
"name": "User-Agent",
"value": "Showpad-Webhook-Agent"
}
],
"method":"GET",
"types":[
"COURSE_COMPLETED"
],
"signatureKey":"5a2d7b35c8427ae4bfe3aa39fe75b68c"
}
The API response includes a signatureKey
it is important to copy and securely store this key as it will only be
visible once. To ensure the authenticity and integrity of the webhook, the signature key can be used to verify the
webhook signature. Refer to the instructions provided in the webhook verification section to
learn how to do this.
Update Subscription
Updating a webhook subscription requires the following HTTP method and endpoint:
HTTP Method | Endpoint | Request body? |
---|---|---|
POST | /subscriptions/{id} Note: The subscription identifier must be included. | Yes |
You can check out the API Specification for more information.
Example
# Update a subscription
curl --request POST \
--url https://{{subdomain}}.api.showpad.com/webhooks/v1/subscriptions/119bc1766eb2433990e5e06412a99f07 \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json' \
--data '{
"name": "my webhook",
"url": "https://my-domain.showpad.com/incoming-webhook",
"method": "GET",
"headers": [
{
"name": "Authorization",
"value": "Bearer xyz"
},
{
"name": "User-Agent",
"value": "Showpad-Webhook-Agent"
}
],
"types": [
"COURSE_COMPLETED"
]
}'
Delete Subscription
Deleting a webhook subscription requires the following HTTP method and endpoint:
HTTP Method | Endpoint | Request body? |
---|---|---|
DELETE | /subscriptions/{id} Note: The subscription identifier must be included. | No |
You can check out the API Specification for more information.
Example
# delete a subscription
curl --request DELETE \
--url https://{{subdomain}}.api.showpad.com/webhooks/v1/subscriptions/119bc1766eb2433990e5e06412a99f07 \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json'
Lists & Logs
The following sections describe how to retrieve information about your subscriptions and view the logs.
Single Subscription
Retrieving a single webhook subscription requires the following HTTP method and endpoint:
HTTP Method | Endpoint | Request body? |
---|---|---|
GET | /subscriptions/{id} Note: The subscription identifier must be included. | No |
You can check out the API Specification for more information.
Example
# Get single subscription
curl --request GET \
--url https://{{subdomain}}.api.showpad.com/webhooks/v1/subscriptions/119bc1766eb2433990e5e06412a99f07 \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json'
All Subscriptions
Retrieving a list of all webhook subscription requires the following HTTP method and endpoint:
HTTP Method | Endpoint | Request body? |
---|---|---|
GET | /subscriptions | No |
You can check out the API Specification for more information.
Example
# Get subscriptions
curl --request GET \
--url https://{{subdomain}}.api.showpad.com/webhooks/v1/subscriptions \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json'
Subscription Logs
Retrieving the logs for a single webhook subscription requires the following HTTP method and endpoint:
HTTP Method | Endpoint | Request body? |
---|---|---|
GET | /subscriptions/{id}/logs Note: The subscription identifier must be included. | No |
You can check out the API Specification for more information.
Example
# Get subscriptions logs
curl --request GET \
--url https://{{subdomain}}.api.showpad.com/webhooks/v1/subscriptions/119bc1766eb2433990e5e06412a99f07/logs \
--header 'Authorization: Bearer MyApiToken' \
--header 'Content-Type: application/json'