Skip to content

HR and hiring

Send Onboarding Packets From BambooHR

Send a new hire an onboarding packet when BambooHR creates the employee, using a BambooHR webhook and an HTTP step in your automation tool.

BambooHR sends a webhook when an employee record is created. Its payload is fixed, so you can’t point the webhook straight at the SignatureAPI REST API. Send it to an inbound webhook in an automation tool, then let that tool’s HTTP step create the envelope. No SignatureAPI app is needed.

The packet is one envelope with two documents and one signer, the new hire. See HR offer letters for the offer stage that comes before it.

Before you start

Receive the new hire from BambooHR

1

Copy the tool's webhook URL

Create an inbound webhook in your automation tool and copy its HTTPS URL. BambooHR accepts only HTTPS URLs.

2

Create the BambooHR webhook

BambooHR has two kinds. Global webhooks are configured by administrators in the BambooHR settings and watch a fixed list of standard fields. Permissioned webhooks are created through the BambooHR API and can watch any field the API user can access, including Hire Date and Status. Choose JSON as the format. See BambooHR webhooks.

3

Read the payload

BambooHR sends an HTTP POST with a list named employees. Each entry has the BambooHR employee id, the changedFields that triggered it and the configured field data in fields. One request can batch several employees, so loop over the list. BambooHR also documents an employee.created event whose data holds only companyId and employeeId; see Employee Created.

4

Look up the name and email if needed

If the payload lacks them, call GET /api/v1/employees/{id}?fields=firstName,lastName,workEmail on your BambooHR domain. Without the fields parameter the response holds only the id. See Get employee.

BambooHR signs deliveries with the X-BambooHR-Signature and X-BambooHR-Timestamp headers, an HMAC-SHA256 over the raw body, the timestamp and your private key. Verify them if your tool lets you.

Send the packet

Add an HTTP step after the webhook and map the employee’s name and email into the body.

HTTP request step

Settings for the "Onboarding packet" request.

SettingValue
Method POST
URL https://api.signatureapi.com/v1/envelopes
Header X-API-Key: YOUR_API_KEY

Store the key in your tool's secret or credential storage when it has one.

Header Content-Type: application/json
Body (raw JSON)The JSON below.
Body (raw JSON)
{
  "title": "Onboarding Packet - Jane Doe",
  "message": "Welcome aboard. Please review and sign your onboarding documents.",
  "metadata": {
    "source": "bamboohr",
    "employee_id": "1042"
  },
  "topics": [
    "hr",
    "onboarding"
  ],
  "documents": [
    {
      "key": "employment_agreement",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "agreement_signature",
          "page": 1,
          "top": 172,
          "left": 210
        }
      ],
      "places": [
        {
          "key": "agreement_signature",
          "type": "signature",
          "recipient_key": "employee"
        }
      ]
    },
    {
      "key": "handbook_acknowledgment",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "handbook_signature",
          "page": 1,
          "top": 172,
          "left": 210
        }
      ],
      "places": [
        {
          "key": "handbook_signature",
          "type": "signature",
          "recipient_key": "employee"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "employee",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ]
}

data.envelope_metadata.employee_id comes back in every webhook event for this envelope, so map the BambooHR employee id there. The onboarding topic lets a SignatureAPI webhook endpoint receive only these envelopes. Both documents share one employee recipient, so the new hire signs the whole packet in one session.

Get the result back

Add a webhook endpoint in the Dashboard, in test mode, pointing at a second inbound webhook in your tool. Subscribe to deliverable.generated, which fires when the signed PDF is ready, and add the onboarding topic. The envelope.completed event comes earlier, while the PDF may still be generating, so use it only to update a status.

Anyone who knows that URL can call it, so read the envelope with your key before you act. The event body gives the envelope in data.envelope_id.

HTTP request step

Settings for the "Completed envelope" request.

SettingValue
Method GET
URL https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56
Header X-API-Key: YOUR_API_KEY

Store the key in your tool's secret or credential storage when it has one.

Act on the response: deliverable.status is generated, metadata.employee_id names the employee, and deliverable.url downloads the signed PDF. That link expires after an hour, so download the file in the same run. If your account uses authenticated deliverable URLs, send your API key with the download.

BambooHR can store the file on the employee record: POST https://{companyDomain}.bamboohr.com/api/v1/employees/{id}/files takes a multipart/form-data body with file, fileName and category (the ID of the employee file section), plus an optional share of yes or no. See Upload Employee File.