Webhooks

Webhooks oferecem a capacidade de receber atualizações de dados sobre as atividade de determinado contato no RD Station.

Você pode escolher receber dados com base em certas ações, como uma nova conversão ou a marcação de uma oportunidade, e ter todos os dados aplicáveis enviados para uma URL de sua escolha. Assim, é possível que você utilize o seu próprio aplicativo personalizado para ler, salvar e realizar ações com esses dados. Esta é uma opção poderosa que permite manter todos os seus dados em sincronia e abre a possibilidade para todos os tipos de integração.

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"
     }
  }
}

Corpo da requisição

O RD Station envia uma requisição com o método configurado no http_method com o cabeçalho Content-Type: application/json . Abaixo seguem os campos disponíveis no campo da requisição:

Nota

Os custom fields são prefixados com "cf_". Caso o campo da entidade não possua valor, não será enviado.


Exemplo:
{
      "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": "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.

Caso nosso serviço de webhooks tenha problemas ao entregar suas notificações, nós tentaremos enviá-las novamente 5 vezes.

Possíveis problemas no envio de notificações:
  • Se seu endpoint de callback demorar mais de 10 segundos para responder.
  • Se a resposta do seu endpoint de callback tiver um status code diferente de 2xx.

Após a falha no envio acontecer, as notificações entram em uma fila para serem re-processadas. Caso o re-envio de uma notificação falhe 5 vezes seguidas, a notificação será marcada como falha e não será re-processada.