API Reference

Webhooks Introduction and Setup

Webhooks

What’s a Webhook?

Webhooks are HTTP requests we send to an Endpoint you provide. They will be executed when certain events occur in our system, such as when a Member joins your account, or when a Member sends you a message.

Availability

Setting up Webhooks in Community requires certain permissions on your account which may be included in your Plan. Please contact [email protected] to inquire about access to the feature.

Configuration

Webhooks can only be configured in the Community Dashboard. Go to Settings → Integrations → Webhooks and click "Configure" (note that this option is only available if you have the appropriate permission), or go directly to https://dashboard.community.com/settings/integrations/webhooks. Any webhooks that have already been configured will be listed. Webhooks can be enabled or disabled directly from this list.

webhooks configuration 2

When a webhook is created or edited a modal window will be displayed. In this modal the name, endpoint URL, and event types to be published can be configured. The endpoint should accept POST requests with the JSON data defined below. A signature secret field will be displayed in this modal as well. The signature secret is unique to each webhook.

webhooks configuration 1

Authentication

To make sure the requests you receive actually originate from Community, we’ve implemented some safeguards.

  1. Only HTTPS endpoints will be accepted
  2. SSL certificates will be verified as valid and for the correct host
  3. Each payload will be signed with a community-signature header generated with the shared signature secret (see Configuration)

The community-signature header will be of the form

community-signature: t=1711666033,v1=b777f6ae2497ae95e99811c88b28d8ba377c95d615905963c68fae4c800de48d

t is the timestamp the request was generated. v1 is the HMAC SHA-256 signature for the request. The signature is generated with the signature secret as the HMAC key and the data is the concatenation of the timestamp, the . character, and the request body.

Event Types

We support subscriptions to the following events:

  1. Inbound messages (Event type: message.inbound): Messages sent from members.
  2. Outbound messages (Event type: message.outbound): Messages sent to a member from your account. Some messages will be filtered out based on whether the content is handled by other Community features, such as help, start, and stop messages; tapbacks, and others. In addition, messages containing text, such as messages with only media, will also be filtered.
  3. Member updates (Event types include member.created, member.updated and member.deleted) Member update events will be published when a new member joins, unsubscribes, deletes themselves, or changes any of the standard personal data collected.

Payloads

Each published event will be a JSON object. At the top level will be fields for the event type, a unique id, the timestamp when the request was created, the api_version being published, a data object holding event specific data, and an object field defining what object is in the data field.

Member update events will include a member object in the event's data field. It will include a unique id for the member, any personal data collected, the communication channel and identifier for the channel (phone number), the timestamp the member was last updated, and whether the member is active (can receive campaigns and DMs).

Inbound and outbound message events will have a message object in the event's data field. It will include a unique id for the message, the text of the message, and a member object with all of the current member data for the sender of the message.

member.created Event Type Sample Payload

{
  "data": {
    "object": {
      "active": true,
      "id": "7a3e02ec-ac2b-952a-9fc0-11b93f283de6",
      "timestamp": "2025-01-16T08:33:47.925975Z",
      "email": "[email protected]",
      "city": "Detroit",
      "country": "United States",
      "client_id": "34e13e8d-241e-52k9-87hf-143322017665",
      "country_code": "US",
      "communication_channel": "sms",
      "date_of_birth": "1990-05-16",
      "communication_channel_id": "12126885505",
      "gender_identity": "male",
      "geolocation": {
        "latitude": 42.331427,
        "longitude": -83.0457538
      },
      "given_name": "John",
      "postal_code": "",
      "state_or_province": "Michigan",
      "state_or_province_abbreviation": "MI",
      "surname": "Smith"
    }
  },
  "id": "4fab65b1-c98f-466e-b52f-c170768a6d89",
  "type": "member.created",
  "object": "member",
  "created": "2025-01-05T23:59:45.643131Z",
  "api_version": "2024-02-12"
}

member.updated Event Type Sample Payload

{
  "data": {
    "object": {
      "active": true,
      "id": "7a3e02ec-ac2b-952a-9fc0-11b93f283de6",
      "timestamp": "2025-01-16T08:33:47.925975Z",
      "email": "[email protected]",
      "city": "Detroit",
      "country": "United States",
      "client_id": "34e13e8d-241e-52k9-87hf-143322017665",
      "country_code": "US",
      "communication_channel": "sms",
      "date_of_birth": "1990-05-16",
      "communication_channel_id": "12126885505",
      "gender_identity": "male",
      "geolocation": {
        "latitude": 42.331427,
        "longitude": -83.0457538
      },
      "given_name": "John",
      "postal_code": "",
      "state_or_province": "Michigan",
      "state_or_province_abbreviation": "MI",
      "surname": "Smith"
    }
  },
  "id": "a2414f4e-a057-4305-946c-79a0cd6049fc",
  "type": "member.updated",
  "object": "member",
  "created": "2025-01-16T08:33:47.950941Z",
  "api_version": "2024-02-12"
}

member.deleted Event Type Sample Payload

{
  "data": {
    "object": {
      "active": false,
      "id": "e9e98f87-ecd4-453c-9b82-5dd0c61f1cda",
      "timestamp": "2025-10-07T20:05:41.051488Z",
      "client_id": "34e13e8d-241e-52k9-87hf-143322017665",
      "communication_channel": "sms",
      "communication_channel_id": ""
    }
  },
  "id": "a2414f4e-a057-4305-946c-79a0cd6049fc",
  "type": "member.deleted",
  "object": "member",
  "created": "2025-01-16T18:00:41.909260Z",
  "api_version": "2024-02-12"
}

message.inbound Event Type Sample Payload

{
  "data": {
    "object": {
      "id": "96c8b483-c16f-4bc3-8f1b-5fe9e1001162",
      "member": {
        "active": true,
        "id": "7a3e02ec-ac2b-952a-9fc0-11b93f283de6",
        "timestamp": "2025-01-16T08:33:47.925975Z",
        "email": "[email protected]",
        "city": "Detroit",
        "country": "United States",
        "client_id": "34e13e8d-241e-52k9-87hf-143322017665",
        "country_code": "US",
        "communication_channel": "sms",
        "date_of_birth": "1990-05-16",
        "communication_channel_id": "12126885505",
        "gender_identity": "male",
        "geolocation": {
          "latitude": 42.331427,
          "longitude": -83.0457538
        },
        "given_name": "John",
        "postal_code": "",
        "state_or_province": "Michigan",
        "state_or_province_abbreviation": "MI",
        "surname": "Smith"
      },
      "text": "Spotify",
      "media_list": [
        {
          "id": "f2dc18ca-3793-439d-a34f-1d140068d3ca",
          "byte_size": null,
          "filename": "twilio-inbound/9aaf09b7-76e9-4a37-8c5b-eed43d62f456/e856be74-6111-4c7a-bfbc-aaf6248a4816.jpg",
          "url": "https://media.community.com/twilio-inbound/9aaf09b7-76e9-4a37-8c5b-eed43d62f456/e856be74-6111-4c7a-bfbc-aaf6248a4816.jpg",
          "width": 1536,
          "mime_type": "image/jpeg",
          "height": 2048,
          "thumbnail_filename": null,
          "thumbnail_url": null,
          "short_url": ""
        }
      ],
      "outbound_message_type": "not_set"
    }
  },
  "id": "82e92c84-c1a7-4cb2-83ca-b7f13ed938d6",
  "type": "message.inbound",
  "object": "message",
  "created": "2025-01-05T21:31:19.740650Z",
  "api_version": "2024-02-12"
}

message.outbound Event Type Sample Payload

{
  "data": {
    "object": {
      "id": "19b736d7-1d45-4572-a1dd-24ff82d4e102",
      "member": {
        "active": true,
        "id": "7a3e02ec-ac2b-952a-9fc0-11b93f283de6",
        "timestamp": "2025-01-16T08:33:47.925975Z",
        "email": "[email protected]",
        "city": "Detroit",
        "country": "United States",
        "client_id": "34e13e8d-241e-52k9-87hf-143322017665",
        "country_code": "US",
        "communication_channel": "sms",
        "date_of_birth": "1990-05-16",
        "communication_channel_id": "12126885505",
        "gender_identity": "male",
        "geolocation": {
          "latitude": 42.331427,
          "longitude": -83.0457538
        },
        "given_name": "John",
        "postal_code": "",
        "state_or_province": "Michigan",
        "state_or_province_abbreviation": "MI",
        "surname": "Smith"
      },
      "text": "Hey Cayleb - looks like you've left some items in your cart!",
      "media_list": [
        {
          "id": "a4b553ad-edce-4c46-a1f6-db2c7e649c9d",
          "byte_size": 433297,
          "filename": "204fa4f6-84e9-4aba-a345-ead7bf4c7316.jpg",
          "url": "https://media.community.com/uploads/34e13e8d-241e-52k9-87hf-143322017665/images/204fa4f6-84e9-4aba-a345-ead7bf4c7316.jpg",
          "width": 800,
          "mime_type": "image/jpeg",
          "height": 450,
          "thumbnail_filename": null,
          "thumbnail_url": null,
          "short_url": "https://m.community.com/mZPjvbMPLru04SC"
        }
      ],
      "outbound_message_type": "automated"
    }
  },
  "id": "30bc3fb5-0c6b-4d6e-8e64-9c93525f8c5c",
  "type": "message.outbound",
  "object": "message",
  "created": "2025-01-05T18:54:21.236681Z",
  "api_version": "2024-02-12"
}

Outbound Message Types:

  • Direct Message: DM
  • Campaign: Campaign
  • Fan Onboarding: Fan_Onboarding
  • Opt-In: Opt_In
  • Opt-Out: Opt_Out
  • Keyword Response: Keyword_Response
  • Seat Onboarding: Seat_Onboarding
  • Help Response: Help_Response
  • Automated: Automated
  • External: External
  • External Customer Support: External_Customer_Support

Implementation Guide

De-Duplication

Webhooks can in some cases be sent more than once for the same object or event as the guarantee is that they will be delivered at-least-once. Care needs to be taken for this on some types of events, for example messages, so that multiple actions are not taken for the same event. For sending messages it's usually recommended to follow the at-most-once principle, it's better to not send a message at all than to send it more than once.

Events should be deduplicated by storing the object or webhook ID for at least an hour and checking if the ID has already been stored before processing the event.

Expected Responses

A 200-299 HTTP status code within 15 seconds. The response body is ignored.

Error Handling and Retries

If the webhook request fails because of an error, such as connection error, a non-2xx response code, or a timeout the request will be retried. Requests will be retried 5 times with an increasing back off, they can be retried for up to an hour of when the first request was sent. An email will be sent to notify you when a webhook continues to fail or timeout. These webhooks may be disabled by Community and can be re-enabled once the situation has been resolved.

Updated 10 months ago

Did this page help you?

Updated 10 months ago

Did this page help you?