Getting Started with Webhooks in Caspio

8 minutes to read

Discover how you can use Caspio Webhooks to automate integrations between apps. If you know this already and want to start implementing webhooks right away, go to the configuration steps.

Sample scenarios

You can use webhooks to integrate your Caspio applications with other systems and efficiently synchronize data between them. Consider the following sample use cases that unlock the potential of webhooks to automate data exchange between services:

Data synchronization
When a customer submits an order on your website, send out order information from Caspio to multiple external systems that handle deliveries. This way you can automate the process, from generating shipping labels to updating the customer with tracking information. You can also use webhooks to back up your data in other services or other Caspio accounts.
Analytics
The moment a new lead is generated in your Caspio app, share the valuable details with an external system that specializes in analytics and reporting. You can use this automation to adjust your sales process and improve your overall performance.
Social media integration
Whenever a new blog post is published on your website, automatically post updates to your company’s social media accounts.
Chatbot integration
When a customer submits a support ticket, notify a chatbot system. Then, the chatbot can provide initial assistance to the customer and assign the ticket to the appropriate support agent.
Marketing campaigns
Notify an external marketing platform when a user completes a specific action, such as signing up for a newsletter or making a purchase. This automation can help you track user engagement and measure campaign success.

Data flow

The implementation of webhooks in Caspio is based on the following relationships between the main elements of this ecosystem:

To start sending data to a target service, you configure a set of rules that govern the data transfer. This set of rules is called an outgoing webhook.
As part of each webhook, you configure events that trigger data delivery. These events are specific activities that occur in the tables in your Caspio application.
When a trigger event occurs, a webhook sends a POST request (a call) that contains a message with a specific payload of data in JSON format. For table.recordUpdate events, a webhook sends a message only if a field value changes.
If the POST request is accepted, the message is delivered, and the target service completes the appropriate actions based on the payload.

Payload

Think of a webhook payload as a notification that contains important information about an event that has happened in one system and needs to be shared with another system. This is the main part of the webhook message which is sent to the outgoing URL. The payload can contain fields related to the webhook itself as well as source table fields. Currently, the payload can consist of the following parameters that you can enter manually or through the Insert parameter dialog:

[@out-hook:eventId]– unique identifier of the event definition
[@out-hook:messageId]– unique identifier of the message, generated based on the event definition and changes in Caspio tables, which you can use to verify if the message is already processed
[@out-hook:callId]– unique identifier of the call that processes the webhook message
[@out-hook:webhookId]– unique identifier of the outgoing webhook definition
[@out-hook:accountId]– unique identifier of the account from which the message is sent
[@out-hook:secret]– value that confirms that the message is sent from Caspio
[@out-hook:eventDate]– timestamp that determines when the event that triggered the message happened in Caspio tables, which you can use to process messages in the correct order in your destination service
[@out-hook:eventType]– action in the source object that triggered the message: table.recordInsert, table.recordDelete, or table.recordUpdate
[@out-hook:objectName]– name of the table where the event occurred
[@out-hook:objectFields] – list of fields that will trigger a webhook (only used for the table.RecordUpdate event)
[@sys:IntegrationURL] – value of the Integration URL parameter available in the account settings
[@field:<fieldName>] – value of the table field that you selected to send as a result of the event (in the “data” section of the default payload, all table fields are listed). For attachment data type, you may choose the value to be included:
- [@field:<attachmentFieldName>] – attachment file name, including the file extension
- [@field:<attachmentFieldName>/] – attachment file URL, which is valid for 300 ms to download the file
[@fielddatatype:<fieldName>] – data type of the table field that you selected

The values in the data parameter are formatted as the following JSON data types:

Table Data Type	JSON DATA TYPE	Example
Autonumber Currency Integer Number PK_ID	Number	`"PK_ID": 7`
Yes/No	Boolean	`"YES/NO": true`
Date/Time Attachment File GUID ID Prefixed Autonumber Random ID Text(255) Text(64k) Timestamp	String	`"IssueDate": "2023-09-13T00:00:00"`
List-String List-Date	String with ID	`"ListString": {"2": "Choice 2","3": "Choice 3"}` `"ListDate": {"1": "2023-09-10T00:00:00","2": "2023-09-11T00:00:00"}`
List-Number	Number with ID	`"ListNumber": {"2": 2,"3": 3}`
Formula	Based on the return field type	`"Price calculation": 123.56` `"Active": true`
(Empty value)	null For the following data types: Currency Date/Time Number Integer List-Date List-Number List-String Timestamp
(Empty value)	“” For the remaining data types.

Note: If a triggered action is enabled for the same event as the webhook, fields with list data types will not be sent in the payload.

You can use the default webhook payload or create a custom payload structure to meet your unique business requirements:

Default payload consists of all webhook-related fields and a data section with either all or selected fields from the source table.
Custom payload contains any webhook and data source table fields that you add.

Review the following examples of default and custom payloads:

Default payload

Custom payload

Note: Because the maximum size of a webhook message is 10 MB, consider how many table fields you want to include in your payload. By default, the payload contains all table fields.

Multicast

To make a single event trigger multiple webhooks at the same time, you can use multicast webhooks. In a multicast webhook scenario, a single event can trigger a webhook to send the same webhook message to multiple outgoing URLs. This approach is useful in scenarios where the same event needs to be distributed to multiple applications or systems.

Note: Access to multicast webhooks depends on your plan.

Call throttling

The external service to which you want to send data with outgoing webhooks might have limits on how many calls it can process. To prevent overload and ensure optimal performance, you can adjust the number of calls the webhooks make with call throttling.

If the number of calls to send exceeds the call throttling value, all the webhook messages are created and queued to be sent in batches. The number of messages in each batch is based on your call throttling settings. To check how many messages were created and sent, you can compare their numbers in the list of webhooks, events, or in logs. For more information, see Testing Webhooks.

Note: The maximum limit that you can set depends on your plan.

Security

Every outgoing webhook definition contains an autogenerated secret key. You can use this key to verify that a message is sent from Caspio. For default payload, every message is signed with a secret key. For custom payload, you need to add the secret key to use it. If your secret key is compromised, you can regenerate it.

To ensure that the webhooks accepted by your system are from trusted sources only, you can configure a list of allowed IP addresses. Learn more.

Caspio Webhook communications use HTTPS to ensure data is protected from interception, tampering, and unauthorized access.

Statistics

You can check the number of messages created, calls sent, and errors received for every webhook and event.

Logs

All activity for every webhook message that is sent is captured in detailed logs. You can use them to troubleshoot issues. Learn more.

Management through REST API

With REST API, you can manage your webhooks and events, which allows you to further automate related tasks and integrate more easily with more services. The tasks that you can complete through REST API include:

Creating and managing webhooks
Creating and managing events
Customizing your payload
Editing outgoing URLs
Adjusting call throttling

To configure and manage webhooks through REST API, you need to create a web services profile with access to all tables, views, files, and file folders in your Caspio account. You set that access with the Enable access to all objects option. Learn more.

Errors

Webhook messages might sometimes fail to deliver or to be processed correctly. All requests that receive an HTML response with codes 4xx and 5xx are treated as errors. You can view details for all errors in logs.

Configuring webhooks

Equipped with the knowledge of what webhooks are and how they work in Caspio, configure webhooks in your apps to automate integrations with other services:

code2

[
  {
    "objectId": 1246965,
    "propertyName": "lifecyclestage",
    "propertyValue": "subscriber",
    "changeSource": "ACADEMY",
    "eventId": 3816279340,
    "subscriptionId": 25,
    "portalId": 33,
    "appId": 1160452,
    "occurredAt": 1462216307945,
    "eventType":"contact.propertyChange",
    "attemptNumber": 0
  },
  {
    "objectId": 1246978,
    "changeSource": "IMPORT",
    "eventId": 3816279480,
    "subscriptionId": 22,
    "portalId": 33,
    "appId": 1160452,
    "occurredAt": 1462216307945,
    "eventType": "contact.creation",
    "attemptNumber": 0
  }
]

code1

{ 
"eventId": "[@out-hook:eventId]", 
"messageId": "[@out-hook:messageId]", 
"webhookId": "[@out-hook:webhookId]", 
"accountId": "[@out-hook:accountId]", 
"secret": "[@out-hook:secret]", 
"eventDate": "[@out-hook:eventDate]", 
"eventType": "[@out-hook:eventType]", 
"objectName": "[@out-hook:objectName]", 
"data": [ { 
            "PK_ID": "[@field:PK_ID]", 
            "First_Name": "[@field:First_Name]", 
            "Last_Name": "[@field:Last_Name]", 
            "Number": "[@field:Number]", 
            "Form": "[@field:Form]", 
            "Number2": "[@field:Number2]",             
            "PersonPicture": "[@field:PersonPicture]"          
        } ] 
}