Webhooks are a way of receiving information from the Oyster platform by getting it "pushed" to you, as opposed to continually making requests ("polling") to the Oyster platform API for updates. For example, one way to use webhooks would be to receive a notification every time an expense is created or approved.

Requirements

To get started with webhooks, you'll need the following:

• A Developer Application. We have a guide on setting one up, but you can also use one you've already created on Oyster.
• An Access Token authorized for the same company (account) that owns the Developer Application (see below).
• A public-facing endpoint (URL) for us to POST webhooks to.

1. Create an Access Token

To register an endpoint to receive webhooks, you will need to make an API request to Oyster. That API request needs to be made with an Access Token authorized for the same company (account) that the Developer Application belongs to.

Partner instructions

1. Log in to Oyster with your company admin account.
2. Visit the Developer Applications page (Company -> Developer from the sidebar)
3. Click on the Authorization URL for your developer application.
4. In the new tab/window, authorize your Developer App to access your company’s data.
5. This will redirect your browser to the Redirect URL specified in your developer application (likely a URL in your own domain). You will need to capture the code parameter included within this redirect as it is required by the next step to create an Access Token.
6. Create a new Access Token for your account using the code captured above: https://docs.oysterhr.com/v0.1/reference/post_oauth2-token-1

Customer instructions

If you are already accessing your data via the Oyster API, then you can create webhook endpoints (step 2) using the same access token(s) you already use to make any other API request. https://docs.oysterhr.com/v0.1/reference/post_oauth2-token-1

2. Set up a webhook endpoint

You'll need to set up a webhook endpoint to receive webhooks to.

To do this, make the following API request, replacing the Bearer token with your access token (from step 1) and replacing the url and sharedSecret with appropriate values:

curl --request POST \
     --url https://api.oysterhr.com/v0.1/webhooks \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <TOKEN GOES HERE>' \
     --header 'content-type: application/json' \
     --data '
{
  "url": "<YOUR WEBHOOK ENDPOINT GOES HERE>",
  "sharedSecret": "<YOUR SHARED SECRET GOES HERE>"
}
'

• url: This is the endpoint you would like us to POST webhooks to.
• sharedSecret: We will include the secret you provide here as an Authorization header (bearer token) in all webhooks we send to you, to prove they've come from the Oyster platform.

This API request will then return the ID of your new webhook endpoint. Make a note of the ID as you'll need it to update or delete the endpoint in the future.

3. Receive a webhook and validate it

Once a webhook endpoint has been registered, the Oyster platform will begin to dispatch webhooks to it as the system responds to events. You'll want to validate that the webhook came from Oyster and you can do this by grabbing the Authorization header from the request and comparing the value to the shared secret that you entered when originally registering the webhook endpoint.

For example, if you use a shared secret of 12345 the Authorization header would be Bearer 12345.

If the two match, the webhook came from Oyster and you can be confident about processing it. In the example above, the two match and the webhook should be processed accordingly.

4. Processing a webhook

Oyster's webhooks follow a defined pattern, set out below:

{
  "event_name": "some_event_name",
  "id": "wh_01J19XRFZ2Q4QBDC6CA461AGT7",
  "company_id": "ABC1234",
  "data" {
    <data relating to the event>
  }
}

• event_name: This is the name of the event generated by the system and will usually be in the format [namespace].event_name. For example, when an expense is approved on Oyster, the event name would be expenses.expense_approved. This will allow you to filter for only the events you care about.
• id: The globally unique ID for this webhook notification. If you have multiple developer applications receiving webhooks for the same logical 'event' (i.e. an expense being approved) then they will each receive a different notification with a different ID. The id will always be prefixed with wh_.
• company_id: The ID of the company for whom the event occurred. For customers, this will be your company ID; for partners, you can use this ID to match against the relevant customer in your system.
• data: A JSON object containing data specific to the event. For example, with an expense.expense_approved event, this would contain the ID of the expense that was approved.