Create Webhook Receiver Synapse
To create an Webhook Receiver Synapse, go to the Custom Synapse tab in Synapse Studio. Click on the "Create New" dropdown and select "Webhook Receiver Synapse". Enter the Display name and API name for the synapse and choose the Authentication type.
We support four authentication types
-
HMAC: Requires a Signature Header, Hash Algorithm, and Client Secret for authentication.
-
BASIC: Requires a Username and Password for authentication.
-
API Key: Requires an API key for authentication.
-
Bearer Token: Requires a Bearer Token for authentication.
Optionally, you can upload an icon for the synapse.
Click Next to proceed to the Payload Configuration step. Here, provide the Record Selector, ID Selector and JSON Schema based on your requirements for the payload.
Record selector: Specify an XPath expression to extract records from an array within the payload. If left blank, the entire payload will be treated as a single record, unless the root of the payload is an array.
ID selector: Enter an XPath expression to specify the field used as the unique identifier (id) when extracting records. Leaving it blank will generate a hash of each record as its identifier. The id field is relative to the record selector.
JSON Schema: Request json schema to parse records from the request.
Eg. Let’s take the following sample payload:
{
"response": [
{
"id": 1,
"name": "Name 1",
"age": 21,
"address": {
"street": "1 Example St",
"city": "City 1",
"state": "State 2",
"country": "Country 2"
},
"updatedAt": "2024-10-10T09:39:19+05:30"
},
{
"id": 2,
"name": "Name 1",
"age": 21,
"address": {
"street": "1 Example St",
"city": "City 1",
"state": "State 2",
"country": "Country 2"
},
"updatedAt": "2024-10-10T09:39:19+05:30"
}
]
}
This payload contains an array called response with two records. Each record represents a person with attributes like id, name, age, address, and updatedAt.
Here’s how you would configure this payload:
-
Record Selector: Use
"response"as the record selector because it identifies the array within the payload that holds the individual records. -
ID Selector: Use
"id"as the ID selector since theidfield is unique for each record. - JSON Schema: Define the structure of each record using the following JSON Schema. This schema validates and parses the data:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Person",
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"age": {
"type": "integer"
},
"address": {
"type": "object",
"properties": {
"street": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
}
}
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
Syncari uses the JSON Schema standard when defining the schema structure and included datatypes. If you want more information about how to build your JSON schema, check out THIS article on creating your first schema. If you are using a website, library, or other service to create your JSON Schema from a sample payload do make sure to not leave any null values or empty objects or arrays. Doing so may result in errors processing the schema.
Click Next to move to the Response step. In this section, you can configure the HTTP Status and Response Template based on your requirements for the response.
Click Next to go to the Test Payload step. Here, test your payload configuration by providing the necessary authentication fields based on the selected authentication type, Additional Request Headers, and Test Payload JSON. Click Test to run the test. The records extracted based on the provided payload appear in the table below. To see the response JSON generated from your configuration, click on the Test Response tab.
Here is a sample payload
{
"response": [
{
"id": 1,
"name": "Name 1",
"age": 21,
"address": {
"street": "1 Example St",
"city": "City 1",
"state": "State 2",
"country": "Country 2"
},
"updatedAt": "2024-10-10T09:39:19+05:30"
},
{
"id": 2,
"name": "Name 1",
"age": 21,
"address": {
"street": "1 Example St",
"city": "City 1",
"state": "State 2",
"country": "Country 2"
},
"updatedAt": "2024-10-10T09:39:19+05:30"
}
]
}
Click Next to review all configurations. Once satisfied, click Create to create the Webhook Receiver Synapse in draft state. When ready, publish the synapse by selecting Publish Draft from the actions column.
Activate Webhook Receiver Synapse
The webhook synapse will appear alongside other synapses in the right-side panel. Drag and drop the synapse onto the canvas and configure it by giving it a name and selecting the Authentication method. The Endpoint URL field, which submits requests to Syncari for processing, is auto-populated and read-only. Click Next. In the following step, authenticate your synapse by providing the credentials required by the selected authentication type. Click Next and activate your synapse.
Create entity pipeline and Sync
Before creating the entity pipeline, ensure your schema is configured correctly by going to the Schema Studio.
Navigate to Sync Studio and create a pipeline for your webhook synapse. Go to the draft entity, configure it based on your requirements, validate, and run tests.
When ready, publish the pipeline. After publishing, open the More Actions dropdown and perform a Resync. The entity pipeline will shift to the running state shortly. Now, you can go to the Data Studio to verify that the entity you created is now populated with data.
Webhook Logs
Once your webhook starts receiving data, you can check the webhook logs from the connection in Synapse Studio. Click on the three dots next to your webhook connection to open the menu and select View Logs. The logs display in a table format within the sidebar, and they are retained for three days.
You can export the logs in CSV format by clicking the Export as CSV button.