Polytomic can deliver data to your API via webhook.

Setup

1. In Polytomic, go to Connections → Add Connection → Webhook.

2. Enter the URL that you'd like Polytomic to deliver payloads to.

3. Polytomic will give you a secret key that you will be able to use to verify incoming payloads with. Hovering over the secret key field will reveal its value.

Once you have set up a sync with desired fields to your webhook connection, Polytomic will send webhook payloads to this address. Payloads will arrive in this format:

POST /path/to/api HTTP/1.1
Host: mysite.com
Accept-Encoding: gzip
Content-Type: application/json
Polytomic-Signature-Timestamp: 2021-06-01T22:55:36Z
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3ZWJob29rIiwianRpIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwiaXNzIjoiaHR0cHM6Ly9hcHAucG9seXRvbWljLWxvY2FsLmNvbTo4NDQzLyJ9.FBSU_fC1YFyWhMSPErRono4BPfkIeT3MkRdZrepiP3c
Content-Length: 646
User-Agent: Polytomic/rel2021.05.25 

{
  "event": "sync.records",
  "object": {
    "id": "1ea8f90a-b22e-4218-86d5-c3c109e1fbb7",
    "name": "Webhook HTTP Endpoint sync",
    "records": [
      {
        "hash": "b7421c6c57bd49f7",
        "fields": {
          "email": "[email protected]",
          "last_login": "2020-12-02T00:00:00Z"
        }
      },
			...
    ]
  }
}

Payload Explanation

Headers

Accept-Encoding
Polytomic delivers payloads as a gzipped response to minimize bandwidth use. Your client likely supports decoding this automatically.

Content-Type
Polytomic delivers its webhooks payloads as json only. This header will always be present.

Polytomic-Signature-Timestamp
This signature lets your backend know when the request was created. In the future it may be used in combination with message signing to provide security. In general, it is a good idea to reject requests older than you expect (more than a few minutes old).

Authorization
This should be a "Bearer" token matching the same value that was provided as the "Secret" during connection setup. For now, this is the only request authorization and is a static value.

Body

{
  # This is an event type to help you distinguish new and future hooks.
  # You should only process webhooks you know about—for right now, that is
  # just the sync.records event.
  "event": "sync.records",
  
  # Object is an envelope that will contain the payload, regardless of event
  "object": {
  
  	# This is the ID of the sync that the webhook is for. It will match
    # the value seen the URL bar when you have the corresponding sync
    # configuration open.
    "id": "1ea8f90a-b22e-4218-86d5-c3c109e1fbb7",
    
    # This name matches the sync setup you created in Polytomic. It can be
    # useful for discriminating against data coming in from different endpoints.
    "name": "Webhook HTTP Endpoint sync",
    
    # This a list of the records changed since the last payload.
    "records": [
      {
        # hash is a computed hash of the record's fields key/values pairs, which 
        # may be useful for deduplicating incoming data.
        "hash": "b7421c6c57bd49f7",
        
        # Fields contains each of the fields you selected to be delivered.
        "fields": {
          "email": "[email protected]",
          "last_login": "2020-12-02T00:00:00Z"
        }
      },
			...
    ],
    "metadata": {
      # Any key-value pairs of metadata defined in the sync configuration
    }
  }
}

Security and Networking

Requests will arrive from Polytomic IP addresses. You may need to allow traffic from Polytomic if your API is protected by a firewall. You can find the list of Polytomic IP addresses here.

Payload API Response

On receipt of the payload, your API should return 200 OK. Any 4xx or 5xx error will cause the sync to appear as a failure.

Advanced settings

At the bottom of your Polytomic sync configuration lies the Advanced settings section. This covers extra optional settings you can modify for your sync:

Here are descriptions for each setting:

Webhook batch size (default: 100)

Polytomic's default batch size when sending to your webhook is 100. You can override this with a webhook batch size of your choice.

Metadata (default: null)

You can specify extra hardcoded keys and values for Polytomic to include in its webhook payload.

Capture webhook requests and responses (default: true)

Leaving this on means you'll get to see a log of each request and response in the Polytomic sync history view.

Always do a full sync (default: false)

Polytomic's Model Syncs are by default differential: only updates/new rows are synced. You can turn this off and have Polytomic always sync everything in the source.

Skip backfill on first sync (default: false)

The first time a Polytomic Model Sync runs, it will sync everything in the source. Subsequent syncs will be automatically differential. You can have Polytomic skip the initial backfill and only sync diffs going forward by setting this to true.