Docs

Webhook event

Alfa asks whether people may be contacted

POSTcontact.check

Sent to your contact check endpoint (set with `PUT /v1/integration/contact-check-endpoint`), not your webhook endpoint. Before outbound sourcing first emails a person found for one of your jobs, Alfa sends your endpoint a signed `POST` (see the `contact-check` webhook) listing the people it is about to contact, each with a `ref` and the identifiers Alfa holds: `email`, `phone` and `linkedinUrl` (any can be null). Answer 200 with `{"results": [{"ref": "src_254928", "contactable": true}]}`, one entry for each `ref`, within 5 seconds. `contactable: false` stops that email and shows the candidate as not to be contacted. Alfa asks at the moment of sending and never caches an answer. Alfa fails closed: if your endpoint times out, cannot be reached, answers with a status other than 2xx, answers in another format, or gives no single clear answer for a person, the email is not sent and the recruiter can retry later.

Alfa sends this request to your contact check endpoint as a signed POST. How to verify and acknowledge webhooks

Headers

  • Alfa-Signaturestringrequired

    `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`, keyed with the endpoint's signing secret. Reject a request whose signature does not match or whose timestamp is more than 5 minutes from your clock.

Payload

  • idstringrequired

    The request id.

  • type"contact.check"required

    Always `contact.check`.

  • apiVersion"v1"required

    The API version the payload follows.

  • requestedAtstringrequired

    When Alfa asked.

  • organizationIdstringrequired

    The company whose outreach this is (its Company ID).

  • peopleobject[]required

    The people Alfa is about to contact. Usually one.

    Show fields
    • refstringrequired

      Identifies this person in the request. Echo it back in your answer.

    • candidateIdstringrequired

      Alfa's id for the sourced candidate.

    • jobIdinteger | nullrequired

      Alfa's id for the job they would be contacted about.

    • externalJobIdstring | nullrequired

      The ATS job the Alfa job is linked to.

    • firstNamestring | nullrequired

      First name.

    • lastNamestring | nullrequired

      Last name.

    • emailstring | nullrequired

      The email address Alfa would write to.

    • phonestring | nullrequired

      Phone number, when Alfa holds one.

    • linkedinUrlstring | nullrequired

      LinkedIn profile URL.

Response body

  • resultsobject[]required

    One answer for each person in the request.

    Show fields
    • refstringrequired

      The `ref` from the request.

    • contactablebooleanrequired

      `true` if Alfa may contact this person; `false` if it must not.

Responses

  • 200Your answer for each person. Any other status, a redirect, a different format or no answer within 5 seconds means nobody in the request is contacted. Alfa does not retry the request; the recruiter can retry the outreach later.