GR API Docs

Webhooks ​

Introduction ​

Webhooks let you send real-time data from GetResponse to any other platform you're using. You can get notified about contact-related events, including subscribes, unsubscribes, and link clicks. View all webhook events

To create a webhook in your GetResponse account, go to Webhooks and click Create webhook. Then, pick the event and provide your webhook URL.

Endpoint specification ​

Here are a few things to keep in mind when setting up and working with webhooks:

  1. Your endpoint needs to be able to process HTTPS requests. So, your app needs to use HTTPS. Make sure your server has a valid SSL certificate configured and installed.

  2. Your endpoint must process the request within 5 seconds. If we don't receive a response, the webhook will timeout, and the connection will close.

  3. To confirm a webhook is received, your endpoint should return one of the following 2xx HTTP status codes:

    • 200 OK
    • 201 Created
    • 202 Accepted
    • 204 No Content

  4. The response body must contain JSON: {"status": "OK"} Without it, the request will be retried despite a 2xx status code.

WARNING

Webhooks will not work properly if the endpoint is not configured according to our endpoint specification.

Authentication ​

To verify a webhook request comes from GetResponse, you can add your own query string parameter at the end of your webhook URL. This will allow you to accept only the requests containing the parameter.

Your URL may look like this: https://www.example-webhook-url.com/?secret=xyz

NOTE

The parameter value and the name can be anything you want.

Retry policy ​

If the webhook request fails because of a network or server issue, we will retry 3 more times at increasing intervals.

Requests that are retried ​

We retry requests for the following reasons:

  • 2xx (if there's no required response body)
  • 429 (Too Many Requests )
  • all 5xx
  • Timeout (no response received within 5 seconds)

Requests that are NOT retried ​

We don't retry requests if your endpoint returns any for the following status codes:

  • 1xx
  • 3xx (redirects)
  • 4xx (except 429)

Webhook batching ​

By default, each event is sent as an individual request, but you can merge many events into a single request. This process is known as batching.

If you expect to receive many events from your GetResponse account, we recommend you batch them to improve the performance of your integration.

Batch specification ​

  • The batch size can vary, but the maximum is 100 events per batch.
  • Depending on your webhook configuration and event volume, different types of webhooks can end up grouped in the same batch without any problem.
  • The payload of batched webhooks is an array filled with objects representing events.
  • Event objects have the typical webhook payload structure. Learn more

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"
        }
    },
    {
        "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"
        }
    }
]

How to batch webhooks ​

  1. Log into your GetResponse account and select Webhooks from the Tools menu.
  2. Create a new webhook or start editing an existing one.
  3. If creating a new webhook, change the webhook status to Active.
  4. Under Webhook batching, switch the toggle button to On.
  5. Save your changes.

Webhooks events ​

You can configure your webhooks to send information about the following events:

  • Message opened - get notified every time a contact opens an email
  • Link clicked - get notified every time a contact clicks a link in an email
  • SMS link clicked - get notified every time a contact clicks a link in a text message (SMS) GetResponse MAX Add-on required
  • Contact subscribed - get notified when a contact is added. This event is not triggered by imports
  • Contact copied - get notified when a contact is copied
  • Contact moved - get notified when a contact is moved
  • Contact unsubscribed - get notified when a contact unsubscribed via unsubscribe link in an email
  • Contact bounce removed - get notified when a contact is removed because of bounce.
  • Custom field value changed - get notified whenever an existing contact has a custom field assigned, unassigned, or updated.

    Note

    Updates via marketing automation and contact imports do not trigger this webhook. It's also not triggered when new contacts with custom fields are added using any method.

  • Contact's email changed - get notified when a contact's email address has changed
  • Import finished - receive a notification when a contact import is complete, and receive information about the status (success/failure) of the import.
  • Contact rejected - get notified when a contact is rejected. This event is not triggered by imports
  • Custom report file status changed - get notified when a custom report is ready for download or in case an error occurs during report generation. There are only two file statuses the webhook is triggered by: [ready, error].

View Webhook payload details