Webhooks
Using webhooks (version 3)
Stillio uses webhooks to notify you of activities. This reference outlines version 3 of the webhooks.
Contents
About webhook requests
- Requests are send to your endpoint, configured in the Stillio app. We support both HTTP and HTTPS endpoints, though we strongly recommend HTTPS
- Requests use the
POSTmethod - Requests do not use authentication. We advise you to hide your endpoint as much as possible so that only known applications - such as Stillio - can send requests
- Requests use JSON-LD 1.0 as method for serializing data
- Requests use shared, established vocabularies for modelling data: Activity Streams 2.0 for activities and Schema.org for webpages and screenshots. For specific properties Stillio uses its own vocabulary
- Requests may change. For example, new properties may be added to the headers or body
How to respond to a webhook request
- Your endpoint should return a
2xxHTTP status code to confirm receipt of a request. All status codes outside this range will indicate to us that you did not receive it. We will try to call your endpoint again up to three times. We will send an email to the email address associated with your Stillio account to notify you of delivery issues - A request to your endpoint times out after 60 seconds. We will then mark the request as failed
- A request does not expect a response payload from your endpoint. Any data that you return in reply to a request is ignored
- A request might occasionally be send more than once to your endpoint. Please guard against duplicated requests by making your processing idempotent, for example by storing the notification and checking whether you have processed it before
Screenshots
Receive a notification if a screenshot has been created
Headers
| Name | Value |
|---|---|
| Content-Type | application/json |
| User-Agent | Stillio-Webhooks/v3 |
| Link | <https://api.stillio.com/v3/contexts>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"; profile="https://www.w3.org/ns/activitystreams" |
Body
| Property | Data type | Description |
|---|---|---|
type | Text | Type of the activity: Create |
summary | Text | Human-readable summary of the activity. Use type for processing by applications |
published | Date, in ISO 8601 date format | Date and time at which the activity was published (UTC) |
actor | URI | The actor that performed the activity, e.g. https://api.stillio.com/v3 |
object | Resource | The object of the activity: a screenshot record |
object.type | Text | Type of the screenshot record: ImageObject |
object.id | URI | URL of the screenshot record (for use with the Stillio API) |
object.identifier | Text | Unique identifier of the screenshot record |
object.isFavorite | Boolean | Flag indicating whether the screenshot record has been marked as favorite (true) or not (false) |
object.dateCreated | Date, in ISO 8601 date format | Date and time at which the screenshot record was created (UTC) |
object.contentUrl | URI | URL of the screenshot image |
object.encodingFormat | Text, in MIME format | Media type of the screenshot image, e.g. image/png |
object.thumbnail | Resource | The thumbnail version of the screenshot image |
object.thumbnail.type | Text | Type of the thumbnail image: ImageObject |
object.thumbnail.contentUrl | URI | URL of the thumbnail image |
object.thumbnail.encodingFormat | Text, in MIME format | Media type of the thumbnail image, e.g. image/png |
object.about | Resource | The webpage record the screenshot record is about |
object.about.type | Text | Type of the webpage record: WebPage |
object.about.id | URI | URL of the webpage record (for use with the Stillio API) |
object.about.identifier | Text | Unique identifier of the webpage record |
object.about.name | Text | Name of the webpage record |
object.about.url | URI | URL of the webpage |
object.about.keywords | List | List of keywords or tags to describe the webpage record |
object.about.isPartOf | Resource | The webpage group the webpage record belongs to |
object.about.isPartOf.type | Text | Type of the webpage group record: WebPageGroup |
object.about.isPartOf.name | Text | Name of the webpage group record. This name is derived from the URL of the webpage |
Example body
{ "type": "Create", "summary": "Stillio created screenshot of webpage", "published": "2019-01-29T11:24:05.743Z", "actor": "https://api.stillio.com/v3", "object": { "type": "ImageObject", "id": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots/{screenshotId}", "identifier": "{screenshotId}", "isFavorite": true, "dateCreated": "2019-01-29T11:23:58.624Z", "contentUrl": "https://stillio-hosting/path/to/image.png", "encodingFormat": "image/png", "thumbnail": { "type": "ImageObject", "contentUrl": "https://stillio-hosting/path/to/thumbnail.png", "encodingFormat": "image/png" }, "about": { "type": "WebPage", "id": "https://api.stillio.com/v3/webpages/{webpageId}", "identifier": "{webpageId}", "name": "Some page", "url": "http://www.example.org/SomePage.html?q=a", "keywords": ["Example1", "Example2"], "isPartOf": { "type": "WebPageGroup", "name": "example.org" } } }}Receive a notification if a screenshot could not be created
Headers
| Name | Value |
|---|---|
| Content-Type | application/json |
| User-Agent | Stillio-Webhooks/v3 |
| Link | <https://api.stillio.com/v3/contexts>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"; profile="https://www.w3.org/ns/activitystreams" |
Body
| Property | Data type | Description |
|---|---|---|
type | Text | Type of the activity: Reject |
summary | Text | Human-readable summary of the activity. Use type for processing by applications |
published | Date, in ISO 8601 date format | Date and time at which the activity was published (UTC) |
actor | URI | The actor that performed the activity, e.g. https://api.stillio.com/v3 |
object | Resource | The object of the activity: a creation activity record |
object.type | Text | Type of the activity record: Create |
object.actor | URI | The actor that performed the activity, e.g. https://api.stillio.com/v3 |
object.object | Resource | The object of the activity: a screenshot record |
object.object.type | Text | Type of the screenshot record: ImageObject |
object.object.id | URI | URL of the screenshot record (for use with the Stillio API) |
object.object.identifier | Text | Unique identifier of the screenshot record |
object.object.isFavorite | Boolean | Flag indicating whether the screenshot record has been marked as favorite (true) or not (false) |
object.object.dateCreated | Date, in ISO 8601 date format | Date and time at which the screenshot record was created (UTC) |
object.object.about | Resource | The webpage record the screenshot record is about |
object.object.about.type | Text | Type of the webpage record: WebPage |
object.object.about.id | URI | URL of the webpage record (for use with the Stillio API) |
object.object.about.identifier | Text | Unique identifier of the webpage record |
object.object.about.name | Text | Name of the webpage record |
object.object.about.url | URI | URL of the webpage |
object.object.about.keywords | List | List of keywords or tags to describe the webpage record |
object.about.isPartOf | Resource | The webpage group the webpage record belongs to |
object.about.isPartOf.type | Text | Type of the webpage group record: WebPageGroup |
object.about.isPartOf.name | Text | Name of the webpage group record. This name is derived from the URL of the webpage |
Example body
{ "type": "Reject", "summary": "Stillio could not create screenshot of webpage", "published": "2019-05-16T11:24:05.743Z", "actor": "https://api.stillio.com/v3", "object": { "type": "Create", "actor": "https://api.stillio.com/v3", "object": { "type": "ImageObject", "id": "https://api.stillio.com/v3/webpages/{webpageId}/screenshots/{screenshotId}", "identifier": "{screenshotId}", "isFavorite": true, "dateCreated": "2019-05-16T11:23:58.624Z", "about": { "type": "WebPage", "id": "https://api.stillio.com/v3/webpages/{webpageId}", "identifier": "{webpageId}", "name": "Some page", "url": "http://www.example.org/SomePage.html?q=a", "keywords": ["Example1", "Example2"], "isPartOf": { "type": "WebPageGroup", "name": "example.org" } } } }}