Webhook events and payloads
Learn about when each webhook event occurs and what the payload contains.
About webhook events and payloads
You have the flexibility to configure webhooks to monitor the events outlined on this page. To optimize the volume of HTTP requests directed to your server, it's advisable to only subscribe to the events you're equipped to manage. For detailed guidance on setting up webhooks, refer to the "Creating webhooks" section.
Descriptions for each webhook event provided here detail the specific properties associated with that event. For events encompassing multiple actions, the properties for each distinct action are delineated.
The applicability of each event varies based on the webhook type. The availability of each webhook event is clarified within its description. For additional information, consult the "Types of webhooks" section.
Delivery Headers
When your configured URL endpoint receives an HTTP POST payload from your webhook, it will include several specific headers:
Header | Description |
---|---|
Content-Type | Indicates the content type of the request (e.g., application/json). |
User-Agent | Identifies the agent sending the request (e.g., Swapcard/Webhook). |
X-Signature-256 | A HMAC hex digest used for request authentication. |
Delivery payload fields
The JSON body of each request will vary based on the action that initiated the request. Below is a list of top-level fields in the payload:
Field | Required | Type | Description |
---|---|---|---|
context | Yes | Object, see here | Includes information such as the event ID, community ID (if the action happened on the community profile) and the user ID. |
profile | Optional, present if action taken on profile | Object | Details of the profile on which the action was taken |
action | Yes | string, one of profile_update , profile_create , profile_delete | Specifies the action. |
datetime | Yes | ISO datetime string | Timestamp of the action |
Example
Here's an example of the HTTP request headers and payload:
> POST /test-endpoint HTTP/2
> X-Signature-256: sha256=c1c39a7af35d5607d90ad008487f2ddd01382c27e27f8e3f23c10731608ea5f4
> User-Agent: Swapcard/Webhook
> Content-Type: application/json
> Content-Length: 1249
{
"context": {
"eventId": "RXZlbnDY1Nc4",
"userId": "VXNlcl25NzcGMA",
"mutation": "updateEventPerson",
"schema": "studio"
},
"action": "profile_update",
"profile" : { ... },
"datetime": "2024-04-01T00:00:00.000Z"
}
Detailed Types
Profile Object
An example of the complete profile object with all its fields is given below:
{
"id": "RXZlbnRQZW9wEGVf7TQx",
"eventId": "RXZlbnDY1Nc4",
"communityProfile": {
"id": "Q29tbXVuaXR5UH3vZmlsDg",
"user": {
"id": "VXNlcl25NzcRBA",
"email": "test@test.com"
},
"firstName": "John",
"lastName": "Doe",
"email": "test@test.com",
"address": {
"street": "Avenue Street",
"city": "Cityville",
"zipCode": "123 456 789",
"state": "Provincestate",
"place": "Big Building",
"country": "Country",
"label": "HOME"
},
"isActive": true,
"isVisible": true,
"engagementScore": 0.438,
"communityId": "Q29tbXVuaXR51GE=",
"jobTitle": "Worker",
"photo": {
"id": "TWVkaWFfMz81Dcz",
"content_type": "image/jpeg",
"public_url": "https://cdn.swapcard.com/public/images/ff048321aef3t458gr5194291.jpeg",
"original_url": "https://cdn.swapcard.com/public/images/ff048321aef3t458gr5194291.jpeg",,
"created_at": "2024-04-01T00:00:00Z",
"updated_at": "2024-04-01T00:00:00Z"
},
"companyName": "Company Inc.",
"phoneNumbers": [
{
"countryCode": 1,
"number": "2345678910",
"label": "HOME"
},
{
"type": "MOBILE",
"countryCode": 98,
"number": "7654321",
"label": "HOME"
}
],
"socialNetworks": [
{
"type": "TWITTER",
"profile": "johndoe"
},
{
"type": "LINKEDIN",
"profile": "johndoe"
}
],
"fieldValues": [
{
"id": "RmllbGRWYWx1E13cMj",
"value": "Webhooks",
"fieldDefinition": {
"id": "RmllbGREZWZpbm12NA",
"name": "Interested in",
"type": "SELECT"
}
},
{
"id": "RmllbGRWYWx1g1ZV8",
"value": "2024-03-15T08:48:00.979Z",
"locale": "pt_BR",
"fieldDefinition": {
"id": "RmllbGREZWZpb81OA",
"name": "Member since"
}
}
],
"communityGroups": [
{
"id": "Q29tbXVuaXR5R3J4MzA4",
"name": "Members"
}
],
"createdAt": "2024-01-01T23:59:59Z",
"updatedAt": "2024-12-31T12:00:00Z"
},
"eventGroups": [
{
"id": "RXZlbnRHcm91cF88xGFOD",
"name": "Attendees",
"eventId": "RXZlbnDY1Nc4",
"communityGroupId": "Q29tbXVuaXR5R3J4MzA4"
}
],
"createdAt": "2024-01-01T23:59:59Z",
"updatedAt": "2024-12-31T12:00:00Z"
}
Payload Details |
---|
id stringUnique identifier for the event person. |
eventId stringUnique identifier for the event. |
communityProfile.id stringUnique identifier for the community profile. |
communityProfile.user.id stringUnique identifier for the user. |
communityProfile.user.email stringEmail address of the user. |
communityProfile.firstName stringFirst name of the community profile user. |
communityProfile.lastName stringLast name of the community profile user. |
communityProfile.email stringEmail address of the community profile. |
communityProfile.address.street stringStreet address of the community profile user. |
communityProfile.address.city stringCity of the community profile user. |
communityProfile.address.zipCode stringZip code of the community profile user. |
communityProfile.address.state stringState of the community profile user. |
communityProfile.address.place stringPlace of the community profile user. |
communityProfile.address.country stringCountry of the community profile user. |
communityProfile.address.label stringLabel for the address. |
communityProfile.isActive booleanIndicates if the profile is active. |
communityProfile.isVisible booleanIndicates if the profile is visible. |
communityProfile.engagementScore numberEngagement score of the community profile. |
communityProfile.communityId stringUnique identifier for the community. |
communityProfile.jobTitle stringJob title of the community profile user. |
communityProfile.photo.id stringUnique identifier for the photo. |
communityProfile.photo.content_type stringContent type of the photo. |
communityProfile.photo.public_url stringPublic URL for the photo. |
communityProfile.photo.original_url stringOriginal URL for the photo. |
communityProfile.photo.created_at stringCreation date of the photo. |
communityProfile.photo.updated_at stringLast update date of the photo. |
communityProfile.photo.deleted_at stringDeletion date of the photo. |
communityProfile.companyName stringCompany name of the community profile user. |
communityProfile.phoneNumbers arrayList of phone numbers for the community profile user. |
communityProfile.socialNetworks arrayList of social networks for the community profile user. |
communityProfile.fieldValues arrayList of field values for the community profile user. |
communityProfile.communityGroups arrayList of community groups the user is part of. |
communityProfile.createdAt stringCreation date of the community profile. |
communityProfile.updatedAt stringLast update date of the community profile. |
communityProfile.deletedAt stringDeletion date of the community profile, if applicable. |
eventGroups arrayList of event groups associated with the event. |
createdAt stringCreation date of the event. |
updatedAt stringLast update date of the event. |