Webhooks integration guide

Integrate webhooks to deliver events to your endpoints.

 

How webhooks work

Webhooks send HTTP POST requests to your endpoints. Each request:

• Carries the full event payload as JSON.
• Follows the CloudEvents specification (opens in a new window).
• Includes an Indeed signature that you verify.

Webhook request format

The webhook system implements the CloudEvents specification (opens in a new window):

Webhook request format

Request	Description
Method	HTTP POST
Content-Type	application/cloudevents+json
Headers	X-Indeed-Signature: HMAC-SHA256 signature for verification. Content-Type: CloudEvents media type, application/cloudevents+json.
Body	JSON payload with event data in CloudEvents format.
Body attributes	Standard CloudEvents attributes: id, source, type, time, datacontenttype, specversion. idempotencykey: unique ID for deduplication and idempotent processing. data: event payload.

HTTP response code handling

HTTP response code handling

Category	HTTP code	Webhook system actions	Partner actions
Success	200 to 299	Marks the delivery complete. Does not retry.	Respond before you process the event.
Redirection	300 to 399	Treats the response as a client error.	Fix your endpoint configuration.
Client errors	400 to 499 (except 429)	Retries with exponential backoff.	Check your endpoint configuration, then fix the endpoint.
Rate limiting error	429	Reads your rate-limiting headers and retries after the delay you specify. Sends no alert.	None.
Server errors	500 to 599	Retries with exponential backoff.	Monitor for 5xx errors and fix your endpoint.

Retry behavior

The webhook system retries a failed delivery until your endpoint accepts it:

Retry behavior

Characteristic	Value
Maximum retry attempts	Effectively unlimited.
Initial retry interval	10 milliseconds
Backoff multiplier	2.0 Doubles the interval after each attempt.
Maximum interval	7,200 seconds (2 hours)

Retries mean an event can arrive more than once and out of order. To handle this, see Use event IDs for idempotent event processing.

Integration steps

Partner integration checklist

Every step is required except where noted.

1. 1.
   Configure an HTTPS endpoint with a valid SSL certificate.
2. 2.
   Implement webhook signature verification — optional.
3. 3.
   Process events asynchronously, responding with 2xx before you process.
4. 4.
   Use event IDs for idempotent event processing.
5. 5.
   Disable CSRF protection for webhook routes.
6. 6.
   Handle errors with appropriate status codes.
7. 7.
   Support rate limiting headers, if applicable.
8. 8.
   Monitor and alert on delivery failures.

---

1. Configure HTTPS endpoint with valid SSL certificate

Create an HTTPS endpoint on your server to receive POST requests. Indeed supports TLS v1.2 and v1.3.

---

2. Implement webhook signature verification

Validate the X-Indeed-Signature header to confirm that Indeed sent the event.

Signature header format:

X-Indeed-Signature: <signature>

---

3. Process events asynchronously

1. Return a 2xx response as soon as you receive the request.
2. Queue the event, and process it after you respond. Otherwise your endpoint can time out.

---

4. Use event IDs for idempotent event processing

Design your webhook handlers to be idempotent. Indeed can deliver the same event more than once, after a retry or a network problem.

To handle duplicates:

• Use event IDs to track the events you already processed.
• Don't rely on event order.

---

5. Disable CSRF protection for webhook routes

If your web framework checks CSRF tokens, exempt your webhook route from this protection.

---

6. Handle errors with appropriate status codes

Return these status codes:

• 2xx: you received the event.
• 429: you are rate limiting Indeed. Include a Retry-After header.
• 5xx: your server failed, so Indeed retries.

---

7. Support rate limiting headers

Supported rate-limiting headers

Header	Description
Retry-After	The webhook system supports these header formats: Seconds: Integer seconds to wait. Retry-After: 120 HTTP date: Absolute timestamp in RFC 1123 (opens in a new window) format. Retry-After: Sat, 21 Oct 2023 07:28:00 GMT
X-RateLimit	UNIX timestamp when the rate limit window resets. X-RateLimit-Reset: 1609459200

If you rate limit Indeed without sending these headers:

• Default wait time: 3 seconds.
• Subsequent retries: exponential backoff.

---

8. Monitor and alert on webhook delivery failures

Monitor webhook delivery:

1. Log every webhook you receive.
2. Track processing success and failure metrics.
3. Alert on repeated failures.

---

See also

Guides

• CloudEvents - Version 1.0.2 (opens in a new window) — A vendor-neutral specification for the format of event data.
• Jobs lifecycle events webhooks guide — Jobs lifecycle status event schema and data schema.

Support

For webhook integration support, contact your Indeed integration team.

 

Was this page helpful?