Webhooks


Webhooks provide the ability to receive real-time data updates about your contact activity.

Choose to receive data based on certain actions, re-cast or marked as an opportunity, and have all applicable data sent to a URL of your choice. You can then use your own custom application to read, save, and do actions with that data. This is a powerful option that allows you to keep all your data in sync and opens the possibility for all types of integration.

Available Methods

Returns a list with all webhook subscriptions from your account.
Response Body
Field Type Description
uuid String The unique uuid associated to each RD Station webhook subscription.
event_type String The event type that triggers the webhook request.
event_identifiers Array of Strings Allows filtering the identifiers of the event that trigger the webhoook. Only for 'WEBHOOK.CONVERTED' events.
entity_type String The entity of the webhook subscription.
url String The webhook destination URL.
http_method String The http method that the webhook will trigger.
include_relations Array of Strings Which additional relations will be provided in the webhook payload.

Example:

Code: 200

{
  "webhooks": [
    {
      "uuid": "5408c5a3-4711-4f2e-8d0b-13407a3e30f3",
      "event_type": "WEBHOOK.CONVERTED",
      "event_identifiers": ["newsletter"],
      "entity_type": "CONTACT",
      "url": "http://my-url.com",
      "http_method": "POST",
      "include_relations": []
    },
    {
      "uuid": "642d985c-487c-4c53-b9de-2c1223841cae",
      "event_type": "WEBHOOK.MARKED_OPPORTUNITY",
      "event_identifiers": [],
      "entity_type": "CONTACT",
      "url": "http://my-url.com",
      "http_method": "POST",
      "include_relations": ["COMPANY", "CONTACT_FUNNEL"]
    }
  ]
}
It creates a webhook subscription.
Request body parameters
Field Type Required Description
event_type String true The event type that triggers the webhook request. Currently only "WEBHOOK.CONVERTED" or "WEBHOOK.MARKED_OPPORTUNITY" are supported.
entity_type String true The entity of the subscription. For now, "CONTACT" is the only accepted option.
event_identifiers Array of Strings false The identifiers from the events that must trigger the webhook. Only for "WEBHOOK.CONVERTED" events.
url String true The webhook destination URL.
http_method String true The http method that the webhook will trigger. Currently only "POST" methods are supported.
include_relations Array of Strings false The relations you would like to include in webhook payload. Only "COMPANY" and "CONTACT_FUNNEL" are supported.

Validations
Attributes validations:
Field Error type Rule
entity_type CANNOT_BE_NULL entity cannot be null
entity_type MUST_BE_STRING entity must be string
entity_type MUST_BE_LESS_THAN_OR_EQUAL entity must less than or equal to 50
entity_type MUST_BE_VALID_OPTION invalid options for entity, the valid options are: CONTACT
event_type CANNOT_BE_NULL event_type cannot be null
event_type MUST_BE_STRING event_type must be string
event_type MUST_BE_LESS_THAN_OR_EQUAL event_type must less than or equal to 50
event_type MUST_BE_VALID_OPTION invalid options for event_type, the valid options are: WEBHOOK.CONVERTED, WEBHOOK.MARKED_OPPORTUNITY
event_identifiers MUST_BE_STRING_ARRAY must be an array of strings
url CANNOT_BE_NULL url cannot be null
url MUST_BE_STRING url must be string
url MUST_BE_LESS_THAN_OR_EQUAL url must less than or equal to 255
url INVALID_URL is not a valid URL.
http_method CANNOT_BE_NULL http_method cannot be null
http_method MUST_BE_STRING http_method must be string
http_method MUST_BE_LESS_THAN_OR_EQUAL http_method must less than or equal to 15
http_method MUST_BE_VALID_OPTION invalid options for http_method, the valid options are: POST
include_relations MUST_BE_VALID_OPTION invalid options for include_relations, the valid options are: COMPANY, CONTACT_FUNNEL

Request body example
{
  "entity_type": "CONTACT",
  "event_type": "WEBHOOK.CONVERTED",
  "event_identifiers": ["newsletter"],
  "url": "http://my-url.com",
  "http_method": "POST",
  "include_relations": ["COMPANY", "CONTACT_FUNNEL"]
}

Response Body
Field Type Description
uuid String The unique uuid associated to each RD Station webhook subscription.
event_type String The event type that triggers the webhook request.
event_identifiers Array of Strings Allows filtering the identifiers of the event that trigger the webhoook. Only for 'WEBHOOK.CONVERTED' events.
entity_type String The entity of the webhook subscription.
url String The webhook destination URL.
http_method String The http method that the webhook will trigger.
include_relations Array of Strings Which additional relations will be provided in the webhook payload.

Response examples:

Success | Code: 201

{
  "uuid": "5408c5a3-4711-4f2e-8d0b-13407a3e30f3",
  "event_type": "WEBHOOK.CONVERTED",
  "event_identifiers": ["newsletter"],
  "entity_type": "CONTACT",
  "url": "http://my-url.com",
  "http_method": "POST",
  "include_relations": ["COMPANY", "CONTACT_FUNNEL"]
}

Error | Code: 400

Attributes errors
{
  "errors": {
    "entity_type": [
      {
          "error_type": "CANNOT_BE_NULL",
          "error_message": "entity_type cannot be null"
      },
      {
        "error_type": "MUST_BE_STRING",
        "error_message": "entity_type must be string"
      },
      {
        "error_type": "MUST_BE_LESS_THAN_OR_EQUAL",
        "error_message": "entity_type must less than or equal to 50"
      },
      {
        "error_type": "MUST_BE_VALID_OPTION",
        "error_message": "invalid options for entity_type, the valid options are: CONTACT"
      }
    ],
    "event_type": [
      {
        "error_type": "CANNOT_BE_NULL",
        "error_message": "event_type cannot be null"
      },
      {
        "error_type": "MUST_BE_STRING",
        "error_message": "event_type must be string"
      },
      {
        "error_type": "MUST_BE_LESS_THAN_OR_EQUAL",
        "error_message": "event_type must less than or equal to 50"
      },
      {
        "error_type": "MUST_BE_VALID_OPTION",
        "error_message": "invalid options for event_type, the valid options are: WEBHOOK.CONVERTED, WEBHOOK.MARKED_OPPORTUNITY"
      }
    ],
    "event_identifiers": [
      {
        "error_type": "MUST_BE_STRING_ARRAY",
        "error_message": "must be an array of strings"
      }
    ],
    "url": [
      {
        "error_type": "CANNOT_BE_NULL",
        "error_message": "url cannot be null"
      },
      {
        "error_type": "MUST_BE_STRING",
        "error_message": "url must be string"
      },
      {
        "error_type": "MUST_BE_LESS_THAN_OR_EQUAL",
        "error_message": "url must less than or equal to 255"
      }
    ],
    "http_method": [
      {
        "error_type": "CANNOT_BE_NULL",
        "error_message": "http_method cannot be null"
      },
      {
        "error_type": "MUST_BE_STRING",
        "error_message": "http_method must be string"
      },
      {
        "error_type": "MUST_BE_LESS_THAN_OR_EQUAL",
        "error_message": "http_method must less than or equal to 15"
      },
      {
        "error_type": "MUST_BE_VALID_OPTION",
        "error_message": "invalid options for http_method, the valid options are: POST"
      }
    ],
    "include_relations": [
      {
        "error_type": "MUST_BE_VALID_OPTION",
        "error_message": "invalid options for include_relations, the valid options are: COMPANY, CONTACT_FUNNEL"
      }
    ]
  }
}
It updates a webhook subscription.
Request body parameters
Field Type Required Description
event_type String true The event type that triggers the webhook request. Currently only "WEBHOOK.CONVERTED" or "WEBHOOK.MARKED_OPPORTUNITY" are supported.
entity_type String true The entity of the subscription. For now, "CONTACT" is the only accepted option.
event_identifiers Array of Strings false The identifiers from the events that must trigger the webhook. Only for "WEBHOOK.CONVERTED" events.
url String true The webhook destination URL.
http_method String true The http method that the webhook will trigger. Currently only "POST" methods are supported.
include_relations Array of Strings false The relations you would like to include in webhook payload. Only "COMPANY" and "CONTACT_FUNNEL" are supported.

Validations
Attributes validations:
Field Error type Rule
entity_type CANNOT_BE_NULL entity cannot be null
entity_type MUST_BE_STRING entity must be string
entity_type MUST_BE_LESS_THAN_OR_EQUAL entity must less than or equal to 50
entity_type MUST_BE_VALID_OPTION invalid options for entity, the valid options are: CONTACT
event_type CANNOT_BE_NULL event_type cannot be null
event_type MUST_BE_STRING event_type must be string
event_type MUST_BE_LESS_THAN_OR_EQUAL event_type must less than or equal to 50
event_type MUST_BE_VALID_OPTION invalid options for event_type, the valid options are: WEBHOOK.CONVERTED, WEBHOOK.MARKED_OPPORTUNITY
event_identifiers MUST_BE_STRING_ARRAY must be an array of strings
url CANNOT_BE_NULL url cannot be null
url MUST_BE_STRING url must be string
url MUST_BE_LESS_THAN_OR_EQUAL url must less than or equal to 255
url INVALID_URL is not a valid URL.
http_method CANNOT_BE_NULL http_method cannot be null
http_method MUST_BE_STRING http_method must be string
http_method MUST_BE_LESS_THAN_OR_EQUAL http_method must less than or equal to 15
http_method MUST_BE_VALID_OPTION invalid options for http_method, the valid options are: POST
include_relations MUST_BE_VALID_OPTION invalid options for include_relations, the valid options are: COMPANY, CONTACT_FUNNEL

Request body example
{
  "entity_type": "CONTACT",
  "event_type": "WEBHOOK.CONVERTED",
  "event_identifiers": ["newsletter"],
  "url": "http://my-url.com",
  "http_method": "POST",
  "include_relations": ["COMPANY", "CONTACT_FUNNEL"]
}

Response Body
Field Type Description
uuid String The unique uuid associated to each RD Station webhook subscription.
event_type String The event type that triggers the webhook request.
event_identifiers Array of Strings Allows filtering the identifiers of the event that trigger the webhoook. Only for 'WEBHOOK.CONVERTED' events.
entity_type String The entity of the webhook subscription.
url String The webhook destination URL.
http_method String The http method that the webhook will trigger.
include_relations Array of Strings Which additional relations will be provided in the webhook payload.

Response examples:

Success | Code: 201

{
  "uuid": "5408c5a3-4711-4f2e-8d0b-13407a3e30f3",
  "event_type": "WEBHOOK.CONVERTED",
  "event_identifiers": ["newsletter"],
  "entity_type": "CONTACT",
  "url": "http://my-url.com",
  "http_method": "POST",
  "include_relations": ["COMPANY", "CONTACT_FUNNEL"]
}

Error | Code: 400

Attributes errors
{
  "errors": {
    "entity_type": [
      {
          "error_type": "CANNOT_BE_NULL",
          "error_message": "entity_type cannot be null"
      },
      {
        "error_type": "MUST_BE_STRING",
        "error_message": "entity_type must be string"
      },
      {
        "error_type": "MUST_BE_LESS_THAN_OR_EQUAL",
        "error_message": "entity_type must less than or equal to 50"
      },
      {
        "error_type": "MUST_BE_VALID_OPTION",
        "error_message": "invalid options for entity_type, the valid options are: CONTACT"
      }
    ],
    "event_type": [
      {
        "error_type": "CANNOT_BE_NULL",
        "error_message": "event_type cannot be null"
      },
      {
        "error_type": "MUST_BE_STRING",
        "error_message": "event_type must be string"
      },
      {
        "error_type": "MUST_BE_LESS_THAN_OR_EQUAL",
        "error_message": "event_type must less than or equal to 50"
      },
      {
        "error_type": "MUST_BE_VALID_OPTION",
        "error_message": "invalid options for event_type, the valid options are: WEBHOOK.CONVERTED, WEBHOOK.MARKED_OPPORTUNITY"
      }
    ],
    "event_identifiers": [
      {
        "error_type": "MUST_BE_STRING_ARRAY",
        "error_message": "must be an array of strings"
      }
    ],
    "url": [
      {
        "error_type": "CANNOT_BE_NULL",
        "error_message": "url cannot be null"
      },
      {
        "error_type": "MUST_BE_STRING",
        "error_message": "url must be string"
      },
      {
        "error_type": "MUST_BE_LESS_THAN_OR_EQUAL",
        "error_message": "url must less than or equal to 255"
      }
    ],
    "http_method": [
      {
        "error_type": "CANNOT_BE_NULL",
        "error_message": "http_method cannot be null"
      },
      {
        "error_type": "MUST_BE_STRING",
        "error_message": "http_method must be string"
      },
      {
        "error_type": "MUST_BE_LESS_THAN_OR_EQUAL",
        "error_message": "http_method must less than or equal to 15"
      },
      {
        "error_type": "MUST_BE_VALID_OPTION",
        "error_message": "invalid options for http_method, the valid options are: POST"
      }
    ],
    "include_relations": [
      {
        "error_type": "MUST_BE_VALID_OPTION",
        "error_message": "invalid options for include_relations, the valid options are: COMPANY, CONTACT_FUNNEL"
      }
    ]
  }
}
It deletes a webhook subscription from the current account.
Request parameters
Field Type Required Description
uuid String true The unique uuid associated to each RD Station webhook subscription.

Response examples:

Success | Code: 204


Error | Code: 404

{
  "errors":{
     {
       "error_type": "RESOURCE_NOT_FOUND",
       "error_message": "the resource couldn't be found"
     }
  }
}

Payload

RD Station triggers a POST request with header Content-Type: application/json along with the following JSON payload:

Note

The custom fields key is populated whenever the Contact's custom fields have values filled different than empty ones.


Example:
{
      "event_type": "WEBHOOK.MARKED_OPPORTUNITY",
      "entity_type": "CONTACT",
      "event_identifier": "my-event-identifier",
      "timestamp": "2018-03-13T14:09:02.724-03:00",
      "event_timestamp": "2018-03-13T14:07:04.254-03:00",
      "contact": {
        "uuid":"c2f3d2b3-7250-4d27-97f4-eef38be32f7f",
        "email":"suporte@resultadosdigitais.com.br",
        "name":"Contact Name",
        "job_title":"Developer",
        "bio":"This is my bio",
        "website": "http://rdstation.com.br",
        "personal_phone":"48 30252598",
        "mobile_phone":"48 30252598",
        "city":"Florianópolis",
        "facebook": "Contact Facebook",
        "linkedin": "Contact Linkedin",
        "twitter": "Contact Twitter",
        "tags": ["tag 1", "tag 2"],
        "cf_custom_field_example": ["Option1", "Option2"],
        "legal_bases": [
          {
            "category": "data_processing",
            "type": "pre_existent_contract",
            "status": "granted"
          },
          {
            "category": "communications",
            "type": "consent",
            "status": "granted"
          }
        ],
        "company": {
          "name": "Company Example 0"
        },
        "funnel": {
          "name": "default",
          "lifecycle_stage": "Lead",
          "opportunity": false,
          "contact_owner_email": "owner@example.org",
          "interest": 20,
          "fit": 0,
          "origin": "Orgânico"
        }
      }
    }
Field Type Description
event_type String The event type that triggered the webhook request.
entity_type String The entity sent in the webhook.
event_identifier String The identifier of the event that triggered the webhook request.
timestamp DateTime The time when the webhook was sent.
event_timestamp DateTime The time when the event that triggered the webhook has occurred.
contact Object The entity itself, could be company or any other supported entity.

If our webhooks service has problems delivering your notifications, we will try sending them again 5 times.

Possible problems in sending notifications include:
  • If your callback endpoint takes longer than 10 seconds to respond.
  • If your callback endpoint response has a status code other than 2xx.

After the sending failure occurs, notifications enter a queue to be reprocessed. If the resend of a notification fails 5 times consecutively, the notification will be marked as failed and will not be reprocessed.