You find great candidates. We help you land them.

What are webhooks?

A webhook is a message that is automatically sent between applications when a specific event occurs. It's the perfect way to connect applications and automate workflows. In Role.so's case you can seamlessly send applicant data — whether interested or declined — to any platform that supports webhooks, including Make, Zapier, and more.

Use cases and examples

You can automate and tailor your workflow to fit every scenario:

Send contact information submitted by interested candidates to a Google spreadsheet
Send an automated text message to a candidate who shown interest in a role
Send a notification in Slack when a candidate is interested or declines a role
Save candidate data to the application tracking system of your choice

Events

When creating a webhook, you can choose from two event types: Interested and Declined. These events map directly to the two forms present on every candidate pack. Once a form is submitted, we'll send a message to all your webhooks matching the event type.

Data

Depending on the event type (interested or declined), we send a fixed data structure. You can use this data to create automations in your applications and enrich your workflow.

Interested data

{
  "event_id": "a9f9f96a-0b5b-418a-ac3b-2b316d24695f", // 🪪 Unique indentifier
  "action": "user_interested", // 🔔 Action type
  "event_timestamp": "2025-02-28T19:08:47.859Z", // 🗓️ Date, as ISO string
  "source": "web_form", // 🌐 Event source
  "source_url": "https://role.so/demo", // 🔌 Candidate pack link where the event occurred
  "payload": {
    "role": "Software Engineer", // 💼 Role, as configured on the candidate pack
    "company": "Acme Inc", // 🏢 Company, as configured on the candidate pack
    "user_details": {
      "name": "Jane Doe", // 👤 Name form field
      "email": "hello@example.com", // ✉️ Email form field
      "phone": "07900000000", // 📞 Phone form field
      "website": "https://linkedin.com", // 🌐 Website URL form field
      "attachments": [
        "https://role.so/mock_webhook_file_1.pdf",
        "https://role.so/mock_webhook_file_2.pdf"
      ] // 🔗 A list of files attached by the candidates
    }
  }
}

Unused/disabled fields will be marked as null. For example, if your candidate pack's interest form has only the name and email fields enabled, we'd send the following data:

{
  // The same data as above
  "user_details": {
    "name": "Jane Doe",
    "email": "hello@example.com",
    "phone": null,
    "website": null,
    "attachments": []
  }
}

Declined data

The decline data is similar in shape to the interest one:

{
  "event_id": "a9f9f96a-0b5b-418a-ac3b-2b316d24695f", // 🪪 Unique indentifier
  "action": "user_declined", // 🔔 Action type
  "event_timestamp": "2025-02-28T19:08:47.859Z", // 🗓️ Date, as ISO string
  "source": "web_form", // 🌐 Event source
  "source_url": "https://role.so/demo", // 🔌 Candidate pack link where the event occurred
  "payload": {
    "role": "Software Engineer", // 💼 Role, as configured on the candidate pack
    "company": "Acme Inc", // 🏢 Company, as configured on the candidate pack
    "decline_reasons": ["Salary", "Perks", "Office location"] // 📋 A list of reasons for declining
  }
}

If you have custom decline reasons configured on your form, we'll send this data instead. For example, if you custom decline reasons are configured to Reason #1 and Reason #2, we'd send the following data:

{
  // The same data as above
  "decline_reasons": ["Reason #1", "Reason #2"]
}

Frequently Asked Questions

Q: Is this feature available on the `Starter` plan?

A: No; this feature is only available on Growth and Scale plan.

Q: How many webhooks can I create?

A: At the moment you can create a maximum of 4 webhooks.

Q: Are events/notifications send real-time?

A: In most of the cases yes, however it can take anywhere between 1 to 5 minutes for the data to be sent to your application.

Q: Can I send test events?

A: Yes, there is an option to send test notifications so you can easily set up your workflow without affecting the stats on your candidate packs. For more about this, have a look at Send a test event help article.

Q: How are failures handled?

A: If a webhooks' endpoint URL fails to receive the data sent by Role.so, we'll retry sending the same event 3 times in total. Should it fail the 3rd time we'll flag the webhook on your webhooks page. For more about this, have a look at Monitoring webhooks help article.

Q: What happens if a webhooks fails over time, will I be notified?

A: Not directly, however we'll flag the webhook as failing and you'll see a Failing badge being added to your webhook. If the failure persist over days and weeks we might automatically disable the problematic webhook. For more about this, have a look at Monitoring webhooks help article.

Webhooks overview