Webhooks integration guide

Integrate webhooks to deliver events to your endpoints.

 

Integration overview

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

Each webhook request has this format:

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 that you use to detect duplicate events. data: event payload.

HTTP response code handling

HTTP response code handling

Category	HTTP code	What Indeed does	What you do
Success	200 to 299	Marks the delivery complete and doesn't 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.	Fix your endpoint or its configuration.
Rate limiting error	429	Retries after the delay in your rate-limiting headers. Doesn't send you an 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).

Because of retries, an event can arrive more than once or out of order.

---

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 an HTTPS endpoint with a valid SSL certificate

Create an HTTPS endpoint on your server to receive POST requests. Indeed supports TLS 1.2 and 1.3.

---

2. Implement webhook signature verification

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

Signature header format:

X-Indeed-Signature: <signature>

---

3. Process events asynchronously

1. 1.
   Queue the event durably.
2. 2.
   Return a 2xx response as soon as you receive the request.
3. 3.
   Process it after you respond, so that your endpoint doesn't time out.

---

4. Use event IDs for idempotent event processing

Make your webhook handlers idempotent, so that processing the same event twice has the same result as processing it once. Indeed can deliver an event more than once after a retry or a network problem.

To handle duplicates:

• Use idempotencykey 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're 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	Use either format: Seconds: Integer seconds to wait. Retry-After: 120 HTTP date: Date and time to retry, in RFC 1123 (opens in a new window) format. Retry-After: Sat, 21 Oct 2023 07:28:00 GMT
X-RateLimit-Reset	Unix timestamp for 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

To monitor webhook delivery:

1. 1.
   Log every webhook you receive.
2. 2.
   Track how many events succeed and fail.
3. 3.
   Set up alerts for repeated failures.

---

See also

Guides

• CloudEvents - Version 1.0.2 (opens in a new window) — Defines a vendor-neutral format for event data.
• Jobs lifecycle events webhooks guide — Describes the event and data schemas for jobs lifecycle status events.

Support

For webhook integration support, contact your Indeed integration team.

 

Was this page helpful?