Webhooks

All payloads are delivered in JSON, to URLs you provide. Each URL can be subscribed to one or more webhook topics. The current topics available for access are:

calls
text_messages (includes WhatsApp messages)
emails
subscriptions

Please get in touch with us at [email protected] to set up a webhook URL once you are ready to accept payloads.

How to integrate

Movement will send a JSON payload directly to your webhook URL in one of the structures below, depending on the event. You are able to provide multiple webhook URLs if you would like to segment the topics by different URLs.

You can either receive these directly to an application which you maintain or can build this webhook into, or receive it into a middleware which you then send onwards to another application. Here are just two examples of how this could work:

Webhooks could be delivered to AWS Lambda, and a function could then decide whether to pass the event on, and transform the payload so it can be posted into a custom application of your own
Webhooks could be delivered to Pipedream, a middleware service which lets you receive JSON payloads, and then integrate directly with 100s of applications
Webhooks can be delivered to Zapier, at which point you can integrate without using any code to thousands of other applications

Calls

Movement can send a webhook every time a call is successfully completed. The payload will be in the following format:

{
  "topic": "call",
  "event": "finished",
  "call": {
    "id": 1050,
    "began_at": "2023-03-21T15:21:26.414Z",
    "duration": 65,
    "outcome": "answer",
    "responses": [
      {
        "id": 4000,
        "created_at": "2023-03-21T15:21:35.690Z",
        "question": {
          "id": 3,
          "text": "Will you attend the training?"
        },
        "answer": {
          "id": 5,
          "text": "Yes"
        }
      }
    ]
  },
  "campaign": {
    "id": 3,
    "name": "New reps - onboarding calls"
  },
  "target": {
    "id": 104,
    "external_id": "MEMBER_1",
    "name": "Cheyenne Pfeffer",
    "organisations": [
      {
        "id": 345,
        "name": "South West",
        "external_id": "demo_region_south_west",
        "type": "region"
      },
      {
        "id": 2,
        "name": "Demo National Organisation",
        "external_id": "national_org",
        "type": "national"
      }
    ]
  },
  "user": {
    "id": 1,
    "name": "Ross Fildes"
  }
}

Further information

A response will be present for every question which was answered
The User object refers to the user who placed the call
IDs refer to internal Movement identifiers (which you can use with our API), with the exception of external_id on Target and Organisation objects. These refer to identifiers specified within your data

Text messages / WhatsApp messages

Movement can send a webhook every time a text message or WhatsApp message is sent or received. The payload will be in the following format:

{
  "topic": "text_message",
  "event": "sent",
  "text_message": {
    "id": 1050,
    "sent_at": "2023-03-21T15:21:26.414Z",
    "body": "Content of text message",
    "media_type": "video/mp4",
    "media_url": "https://..."
  },
  "campaign": {
    "id": 3,
    "name": "New reps - onboarding messages"
  },
  "target": {
    "id": 104,
    "external_id": "MEMBER_1",
    "name": "Cheyenne Pfeffer",
    "organisations": [
      {
        "id": 345,
        "name": "South West",
        "external_id": "demo_region_south_west",
        "type": "region"
      },
      {
        "id": 2,
        "name": "Demo National Organisation",
        "external_id": "national_org",
        "type": "national"
      }
    ]
  },
  "user": {
    "id": 1,
    "name": "Ross Fildes"
  }
}

Further information

The event will be either sent or received, depending on whether the text message was sent from Movement, or received into Movement
User will only be present if a user sent the text message within Movement, which is only the case for peer-to-peer campaigns. Otherwise, this value will be null
IDs refer to internal Movement identifiers (which you can use with our API), with the exception of external_id on Target and Organisation objects. These refer to identifiers specified within your data
media_type and media_url will be null, unless a file was received or sent on the message. This is usually only present for WhatsApp messages

Emails

Movement can send a webhook every time an email is sent. The payload will be in the following format:

{
    "topic": "email",
    "event": "sent",
    "email": {
        "id": 1050,
        "sent_at": "2023-03-21T15:21:26.414Z",
        "body": "Content of email",
        "subject_line:" "Subject line of email"
    },
    "campaign": {
        "id": 3,
        "name": "Email blast name"
    },
    "target": {
        "id": 104,
        "external_id": "MEMBER_1",
        "name": "Cheyenne Pfeffer",
        "organisations": [
            {
                "id": 345,
                "name": "South West",
                "external_id": "demo_region_south_west",
                "type": "region"
            },
            {
                "id": 2,
                "name": "Demo National Organisation",
                "external_id": "national_org",
                "type": "national"
            }
        ]
    }
}

Further information

IDs refer to internal Movement identifiers (which you can use with our API), with the exception of external_id on Target and Organisation objects. These refer to identifiers specified within your data

Subscriptions

Movement can send a webhook every time a target is unsubscribed from either phone, email, SMS, or WhatsApp. The payload will be in the following format:

{
    "topic": "subscription",
    "event": "unsubscribe",
    "subscription": {
        "id": 100,
        "kind": "whatsapp",
        "topic": "default",
        "subscribed": false,
        "organisation": {
            "id": 4,
            "name": "Another Fake Organisation",
            "external_id": "FAKE-ORG-77bde977",
            "type": "Company"
        }
    },
    "target": {
        "id": 2,
        "external_id": "FAKE-TARGET-e7d4c803",
        "organisations": [
            {
                "id": 3,
                "name": "Fake Organisation",
                "external_id": "FAKE-ORG-b2f09eb0",
                "type": "Company"
            },
            {
                "id": 4,
                "name": "Another Fake Organisation",
                "external_id": "FAKE-ORG-77bde977",
                "type": "Company"
            }
        ]
    }
}

Further information

The kind field indicates the communication channel type and can be one of: phone, email, sms, or whatsapp
IDs refer to internal Movement identifiers (which you can use with our API), with the exception of external_id on Target and Organisation objects. These refer to identifiers specified within your data
The organisation object within the subscription represents the specific organisation the target is unsubscribing from
The organisations array within the target contains all organisations associated with the target