GR API Docs

Webhook payloads ​

​

All webhooks share the following:

  • All webhooks provide data in a JSON format
  • All webhooks are sent using the HTTP POST method
  • All href properties link to resource details in GetResponse APIv3
  • All IDs can be used with GetResponse APIv3
  • Each payload contains the following fields:
    • type - event type
    • account - information about the account
    • event - information about the event

Webhook headers ​

Each request will have the following headers:

http
Content-Type: application/json
X-Webhook-Type: contact_removed_link
X-Webhook-ID: 9b287712-80b9-4aba-ad5e-df31929dad75
X-Request-ID: cf3c768a-3465-4a6d-9ad9-ddae2705f526
  • Content-Type - Information about content type application/json
  • X-Webhook-Type - Type of event. Same as type field from the payload
  • X-Webhook-ID - UUID of webhook (unique per event, same for first request and retries)
  • X-Request-ID - UUID of request (unique per request)

Webhook types ​

Message opened ​

Get notified every time a contact opens an email

Payload example
json
{
  "type": "contact_opened_message",
  "contact": {
    "contactId": "abc123",
    "email": "example@example.com",
    "name": "Friend",
    "campaign": {
      "campaignId": "bcd234",
      "name": "my_first_campaign",
      "href": "https://api.getresponse.com/v3/campaigns/bcd234"
    },
    "href": "https://api.getresponse.com/v3/contacts/abc123"
  },
  "message": {
    "resourceType": "autoresponders",
    "resourceId": "cde345",
    "name": "my_first_newsletter",
    "subject": "My First Newsletter",
    "href": "https://api.getresponse.com/v3/autoresponders/cde345"
  },
  "account": {
    "accountId": "def456"
  },
  "event": {
    "occurredAt": "2021-04-27T12:56:00+00:00"
  }
}
Description
  • type - Webhook event type - contact_opened_message
  • contact - Contact who opened the message
    • campaignId - Campaign (list) ID
    • name - Campaign (list) name
    • href - Link to campaign (list) details
    • contactId - Contact ID
    • email - Contact email address
    • name - Name of the contact nullable
    • campaign - Campaign (List) a contact is in
    • href - Link to contact details
  • message - Opened email Newsletter, Autoresponder, or RSS Newsletter)
    • resourceType - Type of the opened message (autoresponders, newsletters, rssNewsletters)
    • resourceId - ID of the opened message
    • name - Name of the opened message
    • subject - Subject of the opened message
    • href - Link to message details
  • account - Information about the account
    • accountId - Account ID
  • event - Information about the event
  • occurredAt - Date of opening message in ISO8601/RFC3339 format

Get notified every time a contact clicks a link in an email

Payload example
json
{
    "type": "contact_clicked_message_link",
    "contact": {
        "contactId": "abc123",
        "email": "example@example.com",
        "name": "Friend",
        "campaign": {
            "campaignId": "bcd234",
            "name": "my_first_campaign",
            "href": "https://api.getresponse.com/v3/campaigns/bcd234"
        },
        "href": "https://api.getresponse.com/v3/contacts/abc123"
    },
    "message": {
        "resourceType": "autoresponders",
        "resourceId": "cde345",
        "name": "my_first_newsletter",
        "subject": "My First Newsletter",
        "href": "https://api.getresponse.com/v3/autoresponders/cde345"
    },
    "clickTrack": {
        "clickTrackId": "xyz789",
        "name": "Some link",
        "url": "http://example.com",
        "href": "https://api.getresponse.com/v3/click-tracks/xyz789"
    },
    "account": {
        "accountId": "def456"
    },
    "event": {
        "occurredAt": "2021-04-27T12:56:00+00:00"
    }
}
Description
  • type - Webhook event type - contact_clicked_message_link
  • contact - Contact who clicked on the message link
    • contactId - Contact ID
    • email - Contact email address
    • name - Name of the contact nullable
    • campaign - Campaign (List) a contact is in
      • campaignId - Campaign (list) ID
      • name - Campaign (list) name
      • href - Link to campaign (list) details
    • href - Link to contact details
  • message - Message (Newsletter, Autoresponder, or RSS Newsletter) that contains the link clicked
    • resourceType - Type of the message (autoresponders, newsletters, rssNewsletters)
    • resourceId - ID of the message
    • name - Name of the message
    • subject - Subject of the message
    • href - Link to the message details
  • clickTrack - Clicked link
    • clickTrackId - ID of the link
    • name - Name of the link
    • url - URL of the link
    • href - Link to the details of the link clicked
  • account - Information about the account
    • accountId - Account ID
  • event

Get notified every time a contact clicks a link in a text message (SMS)

Payload example
json
{
    "type": "contact_clicked_sms_link",
    "contact": {
        "contactId": "abc123",
        "email": "example@example.com",
        "name": "Friend",
        "campaign": {
            "campaignId": "bcd234",
            "name": "my_first_campaign",
            "href": "https://api.getresponse.com/v3/campaigns/bcd234"
        },
        "phoneNumber": {
            "customFieldId": "exdqz",
            "href": "https://api.getresponse.com/v3/custom-fields/exdqz"
        },
        "href": "https://api.getresponse.com/v3/contacts/abc123"
    },
    "sms": {
        "smsId": "cde345",
        "name": "my_first_sms",
        "href": "https://api.getresponse.com/v3/sms/cde345"
    },
    "clickTrack": {
        "clickTrackId": "xyz789",
        "name": "Some link",
        "url": "http://example.com",
        "href": "https://api.getresponse.com/v3/click-tracks/xyz789"
    },
    "account": {
        "accountId": "def456"
    },
    "event": {
        "occurredAt": "2021-04-27T12:56:00+00:00"
    }
}
Description
  • type - Webhook event type - contact_clicked_sms_link
  • contact - Contact who clicked a link in an SMS
    • contactId - Contact ID
    • email - Contact email address
    • name - Name of the contact nullable
    • campaign - Campaign (List) a contact is in
      • campaignId - Campaign (list) ID
      • name - Campaign (list) name
      • href - Link to campaign (list) details
    • phoneNumber - Contact phone number custom field
      • customFieldId - Phone custom field ID
      • href - Link to phone custom field
    • href - Link to contact details
  • sms - SMS (SMS) that contains the link clicked
    • smsId - ID of the SMS
    • name - Name of the SMS
    • href - Link to the SMS details
  • clickTrack - Clicked link
    • clickTrackId - ID of the link
    • name - Name of the link
    • url - URL of the link
    • href - Link to the details of the link clicked
  • account - Information about the account
    • accountId - Account ID
  • event

Contact subscribed ​

Get notified when a contact is added. This event is NOT triggered by imports.

Payload example
json
{
    "type": "contact_added",
    "contact": {
        "contactId": "abc123",
        "email": "example@example.com",
        "name": "Friend",
        "campaign": {
            "campaignId": "bcd234",
            "name": "my_first_campaign",
            "href": "https://api.getresponse.com/v3/campaigns/bcd234"
        },
        "ip": "1.2.3.4",
        "origin": "api",
        "href": "https://api.getresponse.com/v3/contacts/abc123"
    },
    "account": {
        "accountId": "def456"
    },
    "event": {
        "occurredAt": "2021-04-27T12:56:00+00:00"
    }
}
Description
  • type - Webhook event type - contact_added
  • contact - Contact added
    • contactId - ID of added contact
    • email - Email address of added contact
    • name - Name of added contact nullable
    • campaign - Campaign (List) the contact is added to
      • campaignId - ID of campaign (list) the contact is added to
      • name - Name of campaign (list) the contact is added to
      • href - Link to campaign (list) details
    • ip - Contact's IP, if provided nullable
    • origin - How contact was added
    • href - Link to contact details
  • account - Information about the account the contact is added to
    • accountId - Account ID
  • event

Contact copied ​

Get notified when a contact is copied.

Payload example
json
{
  "type": "contact_copied",
  "contact": {
    "contactId": "abc123",
    "email": "example@example.com",
    "name": null,
    "campaign": {
      "campaignId": "bcd234",
      "campaignName": "my new campaign",
      "href": "https://api.getresponse.com/v3/campaigns/bcd234"
    },
    "sourceCampaign": {
      "campaignId": "mnb321",
      "campaignName": "my source campaign",
      "href": "https://api.getresponse.com/v3/campaigns/mnb321"
    },
    "href": "https://api.getresponse.com/v3/contacts/abc123"
  },
  "account": {
    "accountId": "def456"
  },
  "event": {
    "occurredAt": "2021-04-27T12:56:00+00:00"
  }
}
Description
  • type - Webhook event type - contact_copied
  • contact - Contact copied
    • contactId - New contact ID
    • email - New contact email address
    • name - Field deprecated. Presence only for backwards compatibility purpose.
    • campaign - Campaign (List) the contact is copied to
      • campaignId - ID of the campaign (list) the contact is copied to
      • campaignName - Name of the campaign (list) the contact is copied to
      • href - Link to the campaign (list) details
    • sourceCampaign - Campaign (List) the contact is copied from
      • campaignId - ID of the campaign (list) the contact is copied from
      • campaignName - Name of the campaign (list) the contact is copied from
      • href - Link to the campaign (list) details
    • href - Link to contact details
  • account - Information about the account the contact is added to
    • accountId - Account ID
  • event

Contact moved ​

Get notified when a contact is moved.

Payload example
json
{
  "type": "contact_moved",
  "contact": {
    "contactId": "abc123",
    "email": "example@example.com",
    "name": null,
    "campaign": {
      "campaignId": "bcd234",
      "campaignName": "my new campaign name",
      "href": "https://api.getresponse.com/v3/campaigns/bcd234"
    },
    "sourceCampaign": {
      "campaignId": "mnb321",
      "campaignName": "my previous campaign name",
      "href": "https://api.getresponse.com/v3/campaigns/mnb321"
    },
    "href": "https://api.getresponse.com/v3/contacts/abc123"
  },
  "account": {
    "accountId": "def456"
  },
  "event": {
    "occurredAt": "2021-04-27T12:56:00+00:00"
  }
}
Description
  • type - Webhook event type - contact_moved
  • contact - Contact moved
    • contactId - Contact ID
    • email - Contact email address
    • name - Field deprecated. Presence only for backwards compatibility purpose.
    • campaign - Campaign (List) the contact is moved to
      • campaignId - ID of the campaign (list) the contact is moved to
      • campaignName - Name of the campaign (list) the contact is moved to
      • href - Link to the campaign (list) details
    • sourceCampaign - Campaign (List) the contact is moved from
      • campaignId - ID of the campaign (list) the contact is moved from
      • campaignName - Name of the campaign (list) the contact is moved from
      • href - Link to the campaign (list) details
    • href - Link to contact details
  • account - Information about the account the contact is added to
    • accountId - Account ID
  • event

Contact unsubscribed ​

Get notified whenever a contact unsubscribes via unsubscribe link

Payload example
json
{
  "type": "contact_removed_link",
  "contact": {
    "contactId": "abc123",
    "email": "example@example.com",
    "name": null,
    "campaign": {
      "campaignId": "bcd234",
      "name": "my_first_campaign",
      "href": "https://api.getresponse.com/v3/campaigns/bcd234"
    }
  },
  "account": {
    "accountId": "def456"
  },
  "event": {
    "occurredAt": "2021-04-27T12:56:00+00:00"
  }
}
Description
  • type - Webhook event type - contact_removed_link
  • contact - Unsubscribed contact
    • contactId - ID of the contact
    • email - Email address of the contact
    • name - Field deprecated. Presence only for backwards compatibility purpose.
    • campaign - Campaign (List) a contact unsubscribed from
      • campaignId - ID of campaign (list) the contact unsubscribed from
      • name - Name of campaign (list) the contact unsubscribed from
      • href - Link to campaign (list) details
  • account - Information about the account
    • accountId - Account ID
  • event

Bounced contact removed ​

Get notified when a bounced contact is removed from your list.

Payload example
json
{
  "type": "contact_removed_bounce",
  "contact": {
    "contactId": "abc123",
    "email": "example@example.com"
  },
  "campaign": {
    "campaignId": "bcd234",
    "name": "my_first_campaign",
    "href": "https://api.getresponse.com/v3/campaigns/bcd234"
  },
  "account": {
    "accountId": "def456"
  },
  "event": {
    "occurredAt": "2021-04-27T12:56:00+00:00"
  }
}
Description
  • type - Webhook event type - contact_removed_bounce
  • contact - removed contact
    • contactId - ID of the contact
    • email - Contact's email address
  • campaign - Campaign (List) a contact unsubscribed from
    • campaignId - ID of campaign (list) the contact unsubscribed from
    • name - Name of campaign (list) the contact unsubscribed from
    • href - Link to campaign (list) details
  • account - Information about the account
    • accountId - Account ID
  • event

Custom field value changed ​

Get notified whenever an existing contact has a custom field assigned, unassigned, or updated.

Please remember that the webhook is not triggered by:

  • Assigning a custom field when adding a new contact via any method.
  • Updating custom fields values via contact imports.
  • Updating custom field values via marketing automation.
Payload example
json
{
  "type": "contact_custom_field_changed",
  "contact": {
    "contactId": "abc123",
    "href": "https://api.getresponse.com/v3/contacts/abc123"
  },
  "customField": {
    "customFieldId": "cfv123",
    "href": "https://api.getresponse.com/v3/custom-fields/cfv123",
    "action": "changed",
    "addedValues": ["cat", "dog"],
    "removedValues": ["rabbit"]
  },
  "account": {
    "accountId": "def456"
  },
  "event": {
    "occurredAt": "2021-04-27T12:56:00+00:00"
  }
}
Description
  • type - Webhook event type - contact_custom_field_changed
  • contact - contact details
    • contactId - ID of the contact
    • href - Link to contact details
  • customField - Custom field details
    • customFieldId - Custom field ID
    • href - Link to custom field details
    • action - Change type. Possible changes are: added|changed|removed
    • addedValues - Array with new custom field values
    • removedValues - Array with removed custom field values
  • account - Information about the account
    • accountId - Account ID
  • event

Case study ​

  1. The multivalue custom field "pets" is assigned to a contact. The initial state of the custom field is: ["rabbit", "hamster"]
    • A webhook with the following values will be triggered:
     "action": "added",
 "addedValues": ["rabbit", "hamster"],
 "removedValues": []
  2. Your contact has changed the value for the custom field “pets”. The value "rabbit" is removed and two new values are provided: "cat" and "dog".
    • A webhook with the following values will be triggered:
    "action": "changed",
"addedValues": ["cat", "dog"],
"removedValues": ["rabbit"]
  3. Your contact has removed the custom field "pets".
    • A webhook is triggered without custom field values. It looks as follows:
    "action": "removed",
"addedValues": [],
"removedValues": []

Contact's email changed ​

Get notified when a contact's email address has changed.

Payload example
json
{
  "type": "contact_email_changed",
  "contacts": [
    {
      "contactId": "abc123",
      "email": "sample@email.com",
      "href": "https://api.getresponse.com/v3/contacts/abc123",
      "campaign": {
        "campaignId": "bcd234",
        "name": "my_first_campaign",
        "href": "https://api.getresponse.com/v3/campaigns/bcd234"
      }
    },
    {
      "contactId": "def456",
      "email": "sample@email.com",
      "href": "https://api.getresponse.com/v3/contacts/def456",
      "campaign": {
        "campaignId": "efg345",
        "name": "my_second_campaign",
        "href": "https://api.getresponse.com/v3/campaigns/efg345"
      }
    }
  ],
  "account": {
    "accountId": "def456"
  },
  "event": {
    "occurredAt": "2023-07-13T12:56:00+00:00"
  }
}
Description
  • type - Webhook event type - contact_email_changed
  • contacts - List of contacts whose emails were changed
    • contactId - Contact ID
    • email - New email address
    • href - Go to Contact details
    • campaign - Campaign (List)
      • campaignId - Campaign (list) ID
      • name - Campaign (list) name
      • href - Link to the campaign (list) details
  • account - Information about the account the contact is added to
    • accountId - Account ID
  • event

Contact import finished ​

Receive a notification when a contact import is complete, and receive information about the status (success/failure) of the import.

Payload example
json
{
  "type": "contacts_import_finished",
  "status": "OK",
  "account": {
    "accountId": "def456"
  },
  "import": {
    "importId": "abc456",
    "href": "https://api.getresponse.com/v3/imports/abc456"
  }
}
Description
  • type - Webhook event type - contacts_import_finished
  • account - Information about the account
    • accountId - Account ID
  • status - Import status - [ok, failed]
  • import - Information about the import
    • importId - Import ID
    • href - link to import details

Contact rejected ​

Get notified when a contact is rejected. This event is NOT triggered by imports.

Payload example
json
{
  "type": "contact_rejected",
  "contact": {
    "email": "example@gmail.com"
  },
  "account": {
    "accountId": "def456"
  },
  "campaign": {
    "campaignId": "efg345",
    "campaignName": "my_second_campaign",
    "href": "https://api.getresponse.com/v3/campaigns/efg345"
  },
  "event": {
    "occurredAt": "2023-07-13T12:56:00+00:00"
  },
  "reason": "blocked_locally"
}
Description
  • type - Webhook event type - contact_rejected
  • contact - Information about the  contact
    • email - Email of rejected contact
  • account - Information about the account
    • accountId - Account ID
  • campaign - Campaign (List)
    • campaignId - Campaign (list) ID
    • campaignName - Campaign (list) name
    • href - Link to the campaign (list) details
  • event
  • reason - Reason why contact was rejected

Custom report's file status changed ​

Get notified when a custom report file is ready for download or in case an error occurs during report generation.

Payload example
json
{
  "type":"custom_reports_file_status_changed",
  "account":{
    "accountId":"9IJAD"
  },
  "customReport":{
    "customReportId":"v",
    "href":"https://api.getresponse.com/v3/custom-reports/v",
    "file":{
      "customReportFileId":"SE",
      "status":"ready"
    }
  },
  "event":{
    "occurredAt":"2024-08-13T14:34:58+00:00"
  }
}
Description
  • type - Webhook event type - custom_reports_file_status_changed
  • account - Information about the account
    • accountId - Account ID
  • customReport - Custom reports
    • customReportId - Custom report ID
    • href - Link to the custom report details
    • file - Custom report file
      • customReportFileId - Custom report file ID
      • status - status of custom report file - [ready, error]
  • event