Webhooks and callbacks

Ads platform webhooks

2 endpoints.

GET/api/v1/ads/webhook/{platform}

Webhook subscription handshake (returns hub.challenge)

Meta calls this once when the subscription is created — must echo back ``hub.challenge`` if our verify-token matches.

Parameters

Name	In	Type
`platform`required	path	`string`
`hub.mode`required	query	`string`
`hub.challenge`required	query	`string`
`hub.verify_token`required	query	`string`

Responses

200Successful Response

application/jsonany

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/ads/webhook/{platform}

Receive webhook event (signature-verified inline; ack 200 fast)

Verify signature → dispatch by topic → ack.

Verification uses the raw request body — read it before parsing to avoid HMAC mismatch from re-encoding. Failures return 401 silently; Meta retries automatically.