Skip to content
Survey Coder Pro Survey Coder Pro

Register a webhook endpoint

POST
/v2/webhooks
 
curl --request POST \
  --url https://api.surveycoder.io/v2/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "url": "https://example.com", "events": [ "job.completed" ] }'

Register an HTTPS URL to receive event notifications. The server signs every delivery with HMAC-SHA256 over the JSON body using the secret returned here (shown once at creation).

Delivery headers:

  • X-Signature: sha256=<hex> — HMAC of the raw body
  • X-Event — event name (job.completed, job.failed)
  • X-Attempt — 1-4

Retry schedule on non-2xx: immediate, +5s, +30s, +5min (then dropped).

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
url
required

HTTPS endpoint (http URLs are rejected).

string format: uri
events

Subscribed events; defaults to [job.completed, job.failed].

Array<string>
Allowed values: job.completed job.failed *

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Webhook created — secret is shown once and cannot be retrieved later

Media type application/json
object
success
boolean
data
object
id
string
url
string
events
Array<string>
active
boolean
created_at
string format: date-time
secret

Signing secret — store this; shown only once.

string
Example 
{
  "success": true
}

400

Section titled “400 ”

Request body failed validation.

Media type application/json

Standard error envelope.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code. See the error reference for the full list.

string
message
required

Human-readable explanation of what went wrong.

string
request_id

Echo of the X-Request-Id header, when provided.

string format: uuid
doc_url

Link to documentation for this specific error code.

string format: uri
Example 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "responses array is required and must not be empty",
    "doc_url": "https://docs.surveycoder.io/errors/validation-error"
  }
}