Events

Events are a way of being notified of important actions happening within an organization. For example, Polytomic will create a sync.completed event any time a sync finishes. These events are accessible via the events API. We also offer the ability to set up outgoing webhooks which will send realtime events as they happen.

Polytomic is designed for at most once delivery, which means we may fail to send some events. Additionally, events cannot be re-sent once they have been delivered. Therefore, if your use case demands a high level of assurance that all changes to a resource are processed without any missing events, we advise building a fallback polling system that periodically fetches the desired events using the events endpoint.

Retention


Events accessible via the events endpoint are persisted for 48 hours, after which they will not be available.

Event Types

The event types are as follows:

  • sync.running
  • sync.failed
  • sync.canceled
  • sync.completed
  • sync.completed_with_errors
  • bulk_sync.running
  • bulk_sync.completed
  • bulk_sync.canceled
  • bulk_sync.failed
  • bulk_sync.completed_with_error

Webhooks

Webooks can be set up using the webhook API endpoints. Each webhook will fire events for the organization in which it exists. Currently, only one webhook per organization is allowed.

HMAC Validation

HMAC validation can be used to ensure the events you receive are legitimate. When creating or updating a webook, there’s a required secret field. Polytomic will hash each message and include a Polytomic-Signature header in each POST using that secret. You can use the secret field to validate that the signature matches.

Delivery

We require that the endpoint returns a 2xx response code. If a 2xx is not returned, the event will be retried 5 times with exponential backoff. There are no guarantees around ordering.

Record logs

Note that the sync.complete event payload (example illustrated at the bottom of this page) also contains logs (split into JSON files) of records that were inserted or updated by Polytomic. See keys total_records, inserted_records, and updated_records in the event payload.

Event payload examples

1{
2	"type": "bulk_sync.running",
3	"event": {
4		"name": "Asana to BigQuery sync",
5		"organization_id": "be80a27e-0e80-4dcb-bee9-1666f02eeb83",
6		"sync_id": "dcc891b3-4a25-4b8b-bba8-48104cd66525",
7		"execution_id": "8114c8cc-99fc-4fb4-ab72-28308762fa63",
8		"source_connection_id": "ad56197c-1bca-4256-a410-fb1ffde295c0",
9		"destination_connection_id": "318dba62-d875-11ed-b59b-ea7534cffcab"
10   }
11}

1{
2	"type": "bulk_sync.completed",
3	"event": {
4		"name": "Asana to BigQuery sync",
5		"organization_id": "be80a27e-0e80-4dcb-bee9-1666f02eeb83",
6		"sync_id": "dcc891b3-4a25-4b8b-bba8-48104cd66525",
7		"execution_id": "8114c8cc-99fc-4fb4-ab72-28308762fa63",
8		"source_connection_id": "ad56197c-1bca-4256-a410-fb1ffde295c0",
9		"destination_connection_id": "318dba62-d875-11ed-b59b-ea7534cffcab"
10  }
11}

1{
2	"type": "sync.running",
3	"event": {
4		"name": "Salesforce Sync",
5		"organization_id": "be80a27e-0e80-4dcb-bee9-1666f02eeb83",
6		"execution_id": "2a42c650-b741-4282-a4c7-19de797aa18b",
7		"sync_id": "d09ceb2a-1641-4dc8-bdfe-d019d8964043",
8		"target_connection_id": "7c67e0b3-9759-44eb-b96c-2a7042b583f0"
9	}
10}

1{
2	"type": "sync.completed",
3	"event": {
4		"name": "Salesforce Sync",
5		"organization_id": "be80a27e-0e80-4dcb-bee9-1666f02eeb83",
6		"sync_id": "d09ceb2a-1641-4dc8-bdfe-d019d8964043",
7		"execution_id": "2a42c650-b741-4282-a4c7-19de797aa18b",
8		"status": "completed",
9    "total_records": [
10      "https://app.polytomic.com/api/syncs/54d2d580-d910-4bc7-834b-92d57ca89762/executions/c9fd1b24-0b00-46e8-905b-839f919adffd/records/log1688189538-0d74ec71-4540-4706-867f-e6263070e058.json"
11    ],
12    "inserted_records": null,
13    "updated_records": [
14      "https://app.polytomic.com/api/syncs/54d2d580-d910-4bc7-834b-92d57ca89762/executions/c9fd1b24-0b00-46e8-905b-839f919adffd/updates/log1688189542-05f04ffa-3c85-41eb-8333-9d951f93405b.json",
15      "https://app.polytomic.com/api/syncs/54d2d580-d910-4bc7-834b-92d57ca89762/executions/c9fd1b24-0b00-46e8-905b-839f919adffd/updates/log1688189552-6c0bcf4a-b1ae-4cf5-8ee2-dcb6d6fbb728.json"
16		"trigger": "manual",
17		"target_connection_id": "7c67e0b3-9759-44eb-b96c-2a7042b583f0"
18  }
19}

Consuming Events

Below is a brief example (written in Go) of consuming events from a webhook:

1package main
2
3import (
4	"bytes"
5	"crypto/hmac"
6	"crypto/sha256"
7	"encoding/hex"
8	"fmt"
9	"io/ioutil"
10	"net/http"
11
12	"github.com/gin-gonic/gin"
13)
14
15var key = []byte("somepassword")
16
17func main() {
18	r := gin.Default()
19	
20	r.POST("/webhook", func(c *gin.Context) {
21		body, _ := ioutil.ReadAll(c.Request.Body)
22		hash := c.Request.Header.Get("Polytomic-Signature")
23		sig, err := hex.DecodeString(hash)
24		if err != nil {
25			panic(err)
26		}
27		mac := hmac.New(sha256.New, key)
28		mac.Write(body)
29
30		if !hmac.Equal(sig, mac.Sum(nil)) {
31			panic("Invalid signature")
32		}
33
34		fmt.Printf("Headers: %+v, Body: %s", c.Request.Header, string(body))
35		c.Status(http.StatusOK)
36	})
37
38	r.Run("0.0.0.0:8000")
39}