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 - Reasons the contact was rejected

Note

Reasons are dynamic values. They can change at any time.

Reasons:

  • blocked - The address appears on one or more suppression lists (campaign-specific, global, known/suspected, or previously bounced).
  • blocked_invalid_domain - The domain has been identified as unable to receive email messages.
  • blocked_locally - The address is in on a blocklist created in the account.
  • mismatched_criteria - This error occurs when contacts can’t be processed because they don’t match the selected insert option (“add new” or “update existing”). For example, it appears when you try to add contacts that already exist on the list, update contacts that don’t exist yet.
  • policy_issues - The contact was removed automatically after 32 days if unconfirmed or redundant, or had already unsubscribed from your list.
  • syntax_error - The email address is incomplete or incorrect (e.g., “jan@aol”, “johnaol.com”, or “@aol.com” instead of “jan@aol.com”). A syntax error will also occur if the field is empty, contains unsupported special characters (such as !#$%^&()|,), or exceeds 128 characters.
  • other_reason - We couldn’t determine why the contact couldn’t be processed.

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