Webhooks allows you to be notified when some events happen in your MiniApp, such as a new Record is inserted.
Since Platio notifies you using HTTP requests when these events happen, you need to prepare a server or whatever that can receive HTTP requests. Once an event happens in your MiniApp, Platio will deliver information to your server.
This document describes how you get notified with Webhooks. This document assumes that you’re familiar with Platio and some basics about Platio API. If you’re not familiar with Platio API, please read Platio API Programming Guide. This document doesn’t describe how you can handle notifications in various environment such as PHP, Node.js, ASP and so on. Please consult appropriate documents about that.
Currently, Platio can notify when a new Record is inserted, an existing Record is updated, and an existing Record is deleted. It notifies these events by sending a request to your server.
By default, it uses POST requests to send notifications. A body of each request is JSON that contains a Record that is associated with the event. For example, when a new Record is inserted, the body will be something like this.
{
"applicationId": "pkyfjjjmlyffnlgeb5oh2eqs2aa",
"collectionId": "tf71dbb9",
"event": "insertRecord",
"record": {
"id": "rint7fzi2dnhdbezupqgla23eby",
"createdAt": "2017-07-07T01:45:01.612Z",
"updatedAt": "2017-07-07T01:45:01.612Z",
"createdBy": {
"id": "uf598c3f",
"name": "user1"
},
"updatedBy": {
"id": "uf598c3f",
"name": "user1"
},
"values": {
"c002c2c0": {
"type": "String",
"value": "Jeff Scott"
},
"c915a0bc": {
"type": "Number",
"value": 40
}
},
"hash": "cafe99c53ad2e430066d861f40e098a1c02a297a",
"timestamp": "2017-07-07T01:45:01.624Z"
}
}applicationId and collectionId specify an
ID of your Application and Collection respectively. event
can be one of insertRecord, updateRecord or
deleteRecord. As the names imply, they mean a new Record is
inserted, an existing Record is updated, and an existing Record is
deleted.
record property specifies the associated record. You can
find its details in Platio API Programming
Guide. Note that record will have an empty
values when an existing Record is deleted. For example,
it’ll be something like this.
{
"applicationId": "pkyfjjjmlyffnlgeb5oh2eqs2aa",
"collectionId": "tf71dbb9",
"event": "deleteRecord",
"record": {
"id": "rint7fzi2dnhdbezupqgla23eby",
"createdAt": "2017-07-07T01:45:01.612Z",
"updatedAt": "2017-07-07T01:45:01.612Z",
"deletedAt": "2017-07-07T01:45:01.612Z",
"createdBy": {
"id": "uf598c3f",
"name": "user1"
},
"updatedBy": {
"id": "uf598c3f",
"name": "user1"
},
"deletedBy": {
"id": "uf598c3f",
"name": "user1"
},
"values": {
},
"hash": "cafe99c53ad2e430066d861f40e098a1c02a297a",
"timestamp": "2017-07-07T01:45:01.624Z"
}
}When it sends a request, it sets Content-Type of the request to
application/json.
You can transform a request body by setting a rule. A rule needs to be specified using Platio Expressions. The Record will be passed as parameters.
For example, you can specify an expression like this.
{
name: c002c2c0,
age: c915a0bc
}Then, a request will be sent to a server with this body.
{
"name": "Jeff Scott",
"age": 40
}A transformed JSON must be of Object type.
You can send a request to a server only when a record matches a certain condition. You can use Platio Expressions to specify a condition. The Record will be passed as parameters.
When you specify c915a0bc >= 40, for example, a
request will be sent only when a value for this column is greater than
or equal to 40.
The transformed JSON will be converted to query parameters when you
set your Webhook to use GET. Assuming a URL is
http://www.example.org/test, a request will be sent to
http://www.example.org/test?name=Jeff%20Scott&age=40
using GET method if a transformed JSON is the JSON above.
You need to specify a Platio Expression to transform JSON when you use GET. A transformed JSON must be of Object type with all values being String, Number or Boolean values.
The transform JSON will be converted to a form data when you set your Webhook to use POST with Form Data. It’ll send a body like this if a transformed JSON is the JSON above.
name=Jeff%20Scott&age=40In this case, Content-Type of a request becomes
application/x-www-form-urlencoded. As is the case of using
GET, you need to specify a Platio Expression to transform JSON, and a
transformed JSON must be of Object type with all values being String,
Number or Boolean values.
There are some points you need to take care when you implement your server that Platio calls. First, as described above, your server needs to handle POST requests.
Return 2xx response when you process a notification.
Typically, it’ll be 200, but you can return any other
2xx response. It’ll be treated as an error when you return
a response other than 2xx. Redirections will be handled to
some extent.
The body of a response should be empty or at least short. It’ll be ignored anyway. Returning a large body may be treated as an error.
Platio treats it as an error if it cannot get a response within 3 seconds. This includes time to connect to your server, send a request and receive a response. So your server should handle notifications quickly. If you want to do some complex tasks, just return a response before continue processing it, or put notifications to your queue and handle them later.
When Platio fails to connect your server, gets an error response, or doesn’t get a response within a certain period, it’ll retry with some delay up to three times total. When it still fails after the retries, it’ll be treated as an error.
There are two modes in Webhooks. The first mode is strict mode and the other is quick mode.
In the strict mode, all events will be notified in the same order they occurred. For example, when you insert a record, update it, and then deleted it, they’re delivered in this order. Order of events associated with different Records will be reserved, too. Also, it won’t send a notification until the previous notification is handled completely.
In this mode, Platio disables the Webhook as soon as the first error occurs, so that it won’t send notifications out of order. Events after it was disabled will be discarded, so you will only get notified about events after you enable it again.
This mode is useful when you integrate Platio and your system using Webhooks.
In the quick mode, the order of notifications isn’t guaranteed. Platio may send a notification about deleting a record, then one about inserting it, and a notification about updating it. Also, it may send notifications concurrently.
In this mode, Platio continues sending notifications about subsequent events even after it fails. So, even after some errors due to network errors or server failures, it can recover without any actions. However, even in the quick mode, Platio disables the Webhook after a certain amount of errors. Events after it was disabled will be discarded, so you will only get notified about events after you enable it again.
This mode is useful for light integrations, for example, posting it to Slack or sending an email on each event.
Platio logs it when it sent a notification. It includes details of errors when it failed. You can check and download the logs in Platio Studio. If you find your Webhook doesn’t work, check its logs. These logs are available for two weeks.
Special care must be taken when you try to get an Attachment used by the Record associated with an event. Since Attachments are uploaded separately from Records, the associated Attachment might not be available when you get notified with Webhooks. You need to retry by yourself if it’s not available.
There is a limit on how many Webhooks calls you can make in a certain period. The current limitations are listed below, but they may change. These limitations are applied to each Application.
| Webhooks | Limit for Standard and Premium Plan | Limit for Enterprise Plan |
|---|---|---|
| Invocations in Quick Mode | 5,000 invocations / hour | 10,000 invocations / hour |