/webhook/status/{webhook_id}

post

https://partners.apploi.com/webhook/status/{webhook_id}

Reports back to Apploi whether a webhook Apploi sent you was processed successfully on your side.

Apploi delivers an outbound webhook to your endpoint when an application reaches a configured state. Once you have finished processing that delivery, call this endpoint to record the outcome against the application it was sent for. The webhook_id in the path identifies the webhook configuration, and applicant_id in the body identifies the application — together they must match a delivery that Apploi has already made successfully, or the request is rejected with a 400.

When reporting a failure (status is false), error_message is required and must not be blank.

Each call records a new status entry rather than replacing the previous one, so calling this endpoint twice for the same delivery records two entries.

Every request to this endpoint must include your Apploi-issued API key in the x-api-key header.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

webhook_id

string

required

The ID of the Apploi webhook configuration whose delivery you are reporting on. A webhook configuration is the endpoint, credentials, and trigger state Apploi uses to notify you, and this ID is assigned by Apploi when that configuration is created. It is supplied to you by Apploi as part of setting up your webhook integration, and is the same value for every delivery from that configuration.

The webhook configuration identified here must be the one whose delivery for the applicant_id in the request body succeeded; if no such delivery is found, the request is rejected with a 400.

Examples: 42, 43

Body Params

Pass in a JSON body describing the outcome of the webhook delivery. applicant_id and status are always required; error_message is additionally required whenever status is false.

Fields

applicant_id (integer, required): the application form ID the webhook was delivered for. This is the application ID, not the candidate's applicant ID.
status (boolean, required): true if you processed the webhook successfully, false if it failed.
error_message (string): why processing failed. Required and must be non-blank when status is false; ignored when status is true.
link (string): a URL to a resource produced while processing the webhook, such as a completed background check report.

Example — reporting success

{
  "applicant_id": 265733753,
  "status": true,
  "link": "https://vendor.example.com/reports/abc123"
}

Example — reporting a failure

{
  "applicant_id": 265733753,
  "status": false,
  "error_message": "Candidate record could not be matched in our system"
}

The request payload for reporting the outcome of an Apploi webhook delivery via the /webhook/status/{webhook_id} endpoint.

applicant_id

integer

required

The application form ID corresponding to a job application in the Apploi platform. The application form ID is a unique identifier for the job application in the Apploi platform. The application form ID can be found in the 'id' field of the each of the items in the response body of a call to the /applicants endpoint in the Apploi Partner API.

Examples: 265733753, 265733754, etc.

This must be the application the webhook identified by the webhook_id path parameter was delivered for. If Apploi has no record of a successful delivery of that webhook for this application, the request is rejected with a 400.

error_message

string

The reason the webhook could not be processed. This value is ignored when status is true. The error_message field is required, and must not be blank, whenever the status field is false. A request reporting a failure without an error_message is rejected with a 400.

Examples: Candidate record could not be matched in our system

link

string

A URL to a resource produced while processing the webhook, such as a completed background check report. Providing this information is not required to make a successful request.

Examples: https://vendor.example.com/reports/abc123

status

boolean

required

Whether the webhook was processed successfully on your side. Send true when processing succeeded and false when it failed. The error_message field is required, and must not be blank, whenever the status field is false. A request reporting a failure without an error_message is rejected with a 400.

Examples: true, false

Headers

_authorization

string

required

Deprecated: Authorization-header authentication is being sunset in favor of x-api-key authentication, which is now the standard way to authenticate with the Partner API. New integrations should use x-api-key instead — watch for a follow-up communication with removal timelines. The bearer token provided by the /easy-apply and/or /v1/users/login endpoints (depending on the use case). This token should be passed in the 'Authorization' header in the following format: 'Bearer '.

On this endpoint that header is named _authorization rather than Authorization. You do not need to send it: authenticating with the x-api-key header alone is sufficient, and the bearer token is derived from your API key.

Responses

403

The request was rejected before it could be processed. This status is returned with one of two different bodies, depending on where the rejection happened, which is why no single schema is declared for it:

A missing or unrecognized x-api-key header is rejected by the API gateway itself, which returns {"message": "Forbidden"}.
A recognized key that lacks permission for this endpoint, or an expired bearer token, is rejected further in and returns {"developer_message": ...} naming the check that failed.

200The status was recorded. The response body carries a developerMessage of status updated successfully and a status field echoing the HTTP status code. Note that the status field in the response is the integer HTTP status code, and is unrelated to the boolean status field in the request body.

404The webhook_id in the path was not an integer. Note that a well-formed webhook_id with no matching webhook delivery returns a 400, not a 404 — this status only indicates a malformed path.

500The status could not be recorded because of an error on Apploi's side. The request may be retried, but if the original call was applied before the error reached you, the retry records a second entry.