---
updatedAt: 2025-07-01T08:47:39.000Z
---

Fetch the complete documentation index at: https://workable.readme.io/llms.txt. Use this file to discover all available pages before exploring further.

# /subscriptions

Subscribe to an event. Required scope: `r_candidates` or `r_employees`. Accessible with all token types.

You can use this endpoint to register your service. The args object can be used to further filter which candidate events you want to receive. The employee-related events do not use it, so it is advised not to include it.

For Recruiting events, if the args object is present, job\_shortcode and stage\_slug are required. If you want it for all jobs and stages, include an empty string as a parameter for each.\
"job\_shortcode": ""
"stage\_slug": ""

> The target URLs should be unique. If a target URL is already registered, the service will respond with `409 - Conflict`.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "account-root",
    "version": "3.16.2"
  },
  "servers": [
    {
      "url": "https://{subdomain}.workable.com/spi/v3",
      "variables": {
        "subdomain": {
          "default": "subdomain"
        }
      }
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "x-bearer-format": "",
        "x-default": "Bearer"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/subscriptions": {
      "post": {
        "summary": "/subscriptions",
        "description": "Subscribe to an event. Required scope: `r_candidates` or `r_employees`. Accessible with all token types.",
        "operationId": "webhook-subscriptions",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "target",
                  "event"
                ],
                "properties": {
                  "target": {
                    "type": "string",
                    "description": "The URL of the endpoint to push notifications at"
                  },
                  "event": {
                    "type": "string",
                    "description": "One of candidate_created, candidate_moved, employee_created, employee_updated, employee_published, onboarding_completed, timeoff_updated"
                  },
                  "args": {
                    "properties": {
                      "account_id": {
                        "type": "string",
                        "description": "The subdomain of the account, must be included in args"
                      },
                      "job_shortcode": {
                        "type": "string",
                        "description": "Get notifications only for one job. If used, it must be included in args"
                      },
                      "stage_slug": {
                        "type": "string",
                        "description": "Get notifications for specific stages. e.g. 'hired'. If used, it must be included in args"
                      }
                    },
                    "required": [
                      "account_id",
                      "job_shortcode",
                      "stage_slug"
                    ],
                    "type": "object",
                    "description": "Arguments for the subscription"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "201",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"id\": 42\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 42,
                      "default": 0
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "409": {
            "description": "409",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```