Polytomic can deliver data to your API via webhook.

Setup

In Polytomic, go to Connections → Add Connection → Webhook.
Enter the URL that you'd like Polytomic to deliver payloads to.
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.