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
idstring Unique identifier for the event person.
eventIdstring Unique identifier for the event.
communityProfile.idstring Unique identifier for the community profile.
communityProfile.user.idstring Unique identifier for the user.
communityProfile.user.emailstring Email address of the user.
communityProfile.firstNamestring First name of the community profile user.
communityProfile.lastNamestring Last name of the community profile user.
communityProfile.emailstring Email address of the community profile.
communityProfile.address.streetstring Street address of the community profile user.
communityProfile.address.citystring City of the community profile user.
communityProfile.address.zipCodestring Zip code of the community profile user.
communityProfile.address.statestring State of the community profile user.
communityProfile.address.placestring Place of the community profile user.
communityProfile.address.countrystring Country of the community profile user.
communityProfile.address.labelstring Label for the address.
communityProfile.isActiveboolean Indicates if the profile is active.
communityProfile.isVisibleboolean Indicates if the profile is visible.
communityProfile.engagementScorenumber Engagement score of the community profile.
communityProfile.communityIdstring Unique identifier for the community.
communityProfile.jobTitlestring Job title of the community profile user.
communityProfile.photo.idstring Unique identifier for the photo.
communityProfile.photo.content_typestring Content type of the photo.
communityProfile.photo.public_urlstring Public URL for the photo.
communityProfile.photo.original_urlstring Original URL for the photo.
communityProfile.photo.created_atstring Creation date of the photo.
communityProfile.photo.updated_atstring Last update date of the photo.
communityProfile.photo.deleted_atstring Deletion date of the photo.
communityProfile.companyNamestring Company name of the community profile user.
communityProfile.phoneNumbersarray List of phone numbers for the community profile user.
communityProfile.socialNetworksarray List of social networks for the community profile user.
communityProfile.fieldValuesarray List of field values for the community profile user.
communityProfile.communityGroupsarray List of community groups the user is part of.
communityProfile.createdAtstring Creation date of the community profile.
communityProfile.updatedAtstring Last update date of the community profile.
communityProfile.deletedAtstring Deletion date of the community profile, if applicable.
eventGroupsarray List of event groups associated with the event.
createdAtstring Creation date of the event.
updatedAtstring Last update date of the event.