Starting with webhooks

Webhooks allow external services to be notified when certain events happen. When the specified events happen, we’ll send a POST request to each of the URLs you provide.

Setting up a webhook

Go to Settings -> Webhooks -> Add new webhook.

You will see 3 fields:

Name - name your webhook so you can find it later
Payload URL - it's the URL of the server that will receive the webhook POST requests.
Topics - events that you would like to be notified of happening; you can choose multiple.

Once all fields are filled you are ready to go! Save your new webhook and try it out.

Testing webhook

When the event will be triggered PeopleForce will deliver the JSON payload directly as the body of the POST request.
You can give it a try of your webhook by using https://webhook.site/ (WARNING: external link. Please do not send them your real data).

Add your unique URL as Payload URL into your webhook in PeopleForce.
Then go and trigger the selected event (topic), for example, if you want to know about new employees created - create one.
Check the request you received. For the new employee created it would look very similar to this:

{
  "action": "employee_create",
  "data": {
    "id": 130333,
    "attributes": {
      "employee_number": "PF124593",
      "hired_on": "2022-09-12",
      "probation_ends_on": "2022-12-12",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "personal_email": null,
      "gender": "male",
      "mobile_number": "",
      "work_phone_number": "",
      "date_of_birth": "1978-08-31",
      "termination_effective_date": null,
      "termination_comment": null,
      "avatar_url": null
    },
    "reporting_to": {
      "id": 5844,
      "full_name": "Ross Kate",
      "email": "[email protected]"
    },
    "employment_type": {
      "id": 1899,
      "name": "Full-Time"
    },
    "position": {
      "id": 11943,
      "name": "Senior Developer"
    },
    "department": {
      "id": 5094,
      "name": "IT"
    },
    "division": {
      "id": 1819,
      "name": "Europe"
    },
    "location": null,
    "custom_fields": {
      "2692d87e-c388-49ea-b903-616bc1557746": {
        "name": "T-shirt size",
        "value": "M",
        "group": "Personal"
      }
    },
    "meta": {
      "created_at": "2022-09-05T18:33:55.130+03:00",
      "updated_at": "2022-09-05T18:33:55.526+03:00"
    }
  }
}

Webhook execution history

Want to make sure your webhook was sent?
Go to Settings -> Webhooks -> and click on your webhook name.
It will open your history of webhook execution.
Clicking on the name of the delivery you can view the raw data that was sent.

Troubleshooting

Did something go wrong? Maybe you did not receive your webhook or received not what you expected?

Check your Payload URL, make sure it's correct, and that server that will be receiving webhook supports webhooks.
Check the history of your webhook runs. If the webhook was delivered repeat step 1 and proceed to step 3.

200 Success

Webhook was delivered

404 Not Found

The resource could not be found. Please check that your request is referring to an existing object.

500 Internal Server Error

There was a problem with our server. Try again later or contact support to learn more.

Check your recipient server to be up and running and not to have any issues.

If neither of these helps feel free to contact us