Signing the webhooks you send us

​

Where the key comes from

{
  "push_notification_config": {
    "url": "https://api.apostra.com/adcp/source-webhook/17/2009/update_media_buy/17/op_abc123",
    "authentication": {
      "schemes": ["HMAC-SHA256"],
      "credentials": "9f8c2a...e41b"
    }
  }
}

• Not your Apostra API key.
• Not a secret exchanged during onboarding.
• Not shared across your integrations.

​

The signature

HMAC-SHA256(credentials, "{timestamp}.{rawBody}")

1. sha256= is part of the header value. X-ADCP-Signature: sha256=a1b2c3..., not the bare hex.
2. The timestamp is in seconds, not milliseconds. Date.now() in JavaScript and System.currentTimeMillis() in Java both return milliseconds; divide by 1000 and floor.
3. The timestamp is part of the signed message. Signing the body alone is the scheme our buyer webhook docs describe, and it will not verify here.
4. Sign the exact bytes you send. Serialize the body once, sign those bytes, send those bytes. Do not re-serialize between signing and sending: a different key order or whitespace changes the digest.

​

Reference implementation

import crypto from 'node:crypto'

async function sendWebhook(url, credentials, payload) {
  // Serialize once. These are the bytes we sign AND the bytes we send.
  const rawBody = JSON.stringify(payload)
  const timestamp = Math.floor(Date.now() / 1000).toString()

  const digest = crypto
    .createHmac('sha256', credentials)
    .update(`${timestamp}.${rawBody}`, 'utf8')
    .digest('hex')

  return fetch(url, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-adcp-timestamp': timestamp,
      'x-adcp-signature': `sha256=${digest}`,
    },
    body: rawBody,
  })
}

import hashlib
import hmac
import json
import time

import requests


def send_webhook(url: str, credentials: str, payload: dict):
    # Serialize once. These are the bytes we sign AND the bytes we send.
    raw_body = json.dumps(payload)
    timestamp = str(int(time.time()))

    digest = hmac.new(
        credentials.encode("utf-8"),
        f"{timestamp}.{raw_body}".encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return requests.post(
        url,
        data=raw_body.encode("utf-8"),
        headers={
            "content-type": "application/json",
            "x-adcp-timestamp": timestamp,
            "x-adcp-signature": f"sha256={digest}",
        },
    )

package webhook

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"net/http"
	"strconv"
	"time"
)

func SendWebhook(url, credentials string, payload any) (*http.Response, error) {
	// Marshal once. These are the bytes we sign AND the bytes we send.
	rawBody, err := json.Marshal(payload)
	if err != nil {
		return nil, err
	}
	timestamp := strconv.FormatInt(time.Now().Unix(), 10)

	mac := hmac.New(sha256.New, []byte(credentials))
	fmt.Fprintf(mac, "%s.%s", timestamp, rawBody)
	digest := hex.EncodeToString(mac.Sum(nil))

	req, err := http.NewRequest("POST", url, bytes.NewReader(rawBody))
	if err != nil {
		return nil, err
	}
	req.Header.Set("content-type", "application/json")
	req.Header.Set("x-adcp-timestamp", timestamp)
	req.Header.Set("x-adcp-signature", "sha256="+digest)

	return http.DefaultClient.Do(req)
}

​

RFC 9421 message signatures

• An https agent endpoint that answers get_adcp_capabilities without credentials, over the protocol you registered with us (MCP or A2A). We read your capabilities first, because they tell us where your brand.json lives. See Connect your sales agent.
• A brand.json whose agents[] entry for your endpoint has the same URL as the endpoint we call and declares a jwks_uri. This is how we resolve your public keys.
• Signature and Signature-Input headers on each delivery.

1. If your capabilities declare identity.brand_json_url, we fetch that URL. It must be https. When it is on a different registrable domain from your agent, that brand.json must list your agent’s domain in authorized_operators[].
2. If you are an AdCP 3.x agent and declare no identity.brand_json_url, we fetch /.well-known/brand.json on your agent’s origin. When that returns 404 or 410, we try your registrable domain (for example example.com for agent.example.com). We follow at most one authoritative_location or house redirect from there.
3. An AdCP 4.0 agent must declare identity.brand_json_url. The well-known fallback does not apply.

​

Creative-sync callbacks

• An HMAC-signed delivery to a URL registered without a credential is refused with 401, even with the right key. We never gave you a credential for it.
• An RFC 9421 delivery for a call that carried a credential is refused with 401.

​

Which scheme am I implementing?

​

Troubleshooting a rejected webhook

​

Verifying the webhooks we send you