Authentication

API Base URL

Unless otherwise specified, all endpoints use https://api.bem.ai as their base URL.

API Keys

For all requests, you'll need an API key. Pass this in using an x-api-key header.

Webhook Authentication

To confirm authenticity of webhook requests coming from bem, we provide a bem-signature header on every outgoing request to the endpoint specified in your pipeline. The header value includes a timestamp (t=) and a signature (v1=); these values are comma-separated, and the scheme will be versioned in case of future updates.

bem-signature:
t=1492774577,
v1=0734be64d748aa8e8ee9dfe87407665541f2c33f9b0ebf19dfd0dd80f08f504c

Signatures are generated using HMAC with SHA-256. The webhook secret for your account can be generated, retrieved, and revoked through our API, and we use that secret to encode the payload into the signature we present in the header.

To verify the signature, you must complete the following steps:

Step 1: Extract timestamp and signature from header

Split the raw string to grab the respective t timestamp and v1 signature values.

Step 2: Prepare the signed payload string

The payload string is created by concatenating:

• The timestamp (as a string)
• The character .
• The actual JSON payload (stringified request body)

Step 3: Determine the expected signature

Compute an HMAC with the SHA-256 hash function (the string output should be in hex). Use your account's webhook secret as the key, and the signed payload string as the message.

Step 4: Compare the signatures

Compare your computed signature with the signature provided in the header doing a simple string equality check. If the signatures match, you've validated that the request to your webhook endpoint is coming from bem.

Pagination

Our pagination follows the same conventions as the Stripe API, allowing you to use cursors to page back-and-forth through results. Our API uses cursor-based pagination through startingAfter and endingBefore parameters. Both parameters accept an existing object ID value and return objects in chronological order. The endingBefore parameter returns objects listed before the given object. The startingAfter parameter returns objects listed after the given object. These parameters are mutually exclusive. You can use either the startingAfter or endingBefore parameter, but not both simultaneously. An limit parameter can be optionally provided to control the page size and our API defaults to a page size of 50 if a limit is not provided.