Webhooks guide

Integrate webhooks to deliver events to your endpoints.

 

Overview

Indeed webhooks deliver events to partner endpoints. This guide covers how webhooks work, integration, and best practices.

Webhooks workflow

1. 1.
   Learn how webhooks work.
2. 2.
   Integrate with the webhook system.

How webhooks work

Webhooks send HTTP POST requests with event notifications to your endpoints. Each delivery:

• Contains the full event payload in JSON format
• Uses CloudEvents specification
• Includes an Indeed signature for authenticity
• Follows best practices for reliable delivery

HTTP response code handling

This table describes how the webhook system handles HTTP response codes from your endpoint:

HTTP response code handling

Category	HTTP code	Webhook system actions	Partner actions
Success	200 to 299	Marks delivery as complete. No retries.	Respond before performing complex processing.
Redirection	300 to 399	Treats as a client error.	Review and fix the endpoint configuration.
Client errors	400 to 499 (except 429)	Treats as a client error. Retries with exponential backoff.	Fix client-side endpoint issues. Investigate promptly for configuration problems.
Rate limiting error	429	Respects rate limiting headers (see Supported rate limiting headers). Retries after the specified delay. No alerts triggered.	No action needed. Rate limits are automatically respected.
Server errors	500 to 599	Retries with exponential backoff.	Fix server-side endpoint issues. Monitor for 5xx errors and resolve underlying causes.

Retry behavior

The webhook system ensures reliable delivery through retries:

Retry behavior

Characteristic	Value
Maximum retry attempts	Integer.MAX_VALUE Effectively unlimited retries.
Initial retry interval	10 milliseconds
Backoff multiplier	2.0 Doubles the interval after each attempt. For error codes (except 429), retries use exponential backoff.
Maximum interval	7,200 seconds (2 hours)

Consider:

• Idempotency: Design webhook handlers to process the same event multiple times without side effects.
• Deduplication: Use the event ID to filter duplicates.
• Processing order: Events may arrive out of order. Use timestamps and IDs for sequencing.

Webhook request format

The webhook system fully implements the CloudEvents specification:

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.

Integrate with the webhook system

For information about the jobs lifecycle status event schema and data schema, see the Jobs lifecycle events webhooks guide.

Partner integration checklist

Partner integration checklist

Step	Description	Required
1.	Configure HTTPS endpoint with a valid SSL certificate.	✓
2.	Implement webhook signature verification.
3.	Process events asynchronously. Send quick 2xx response before processing.	✓
4.	Use event IDs for idempotent event processing.	✓
5.	Disable CSRF protection for webhook routes.	✓
6.	Handle errors with appropriate status codes.	✓
7.	Support rate limiting headers, if applicable.	✓
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. Production webhook endpoints must use HTTPS. Supports TLS v1.2 and v1.3.

2. Implement webhook signature verification

Validate the X-Indeed-Signature header to ensure authenticity and prevent fake events.

Signature header format:

X-Indeed-Signature: <signature>

3. Process events asynchronously

1. Return a 2xx response immediately upon receipt.
2. Queue the event for processing after responding to prevent timeout issues.

4. Use event IDs for idempotent event processing

Design webhook handlers to be idempotent. Events can be delivered multiple times due to retries, network issues, or manual retries.

To handle duplicates:

• Use event IDs to track processed events.
• Handle duplicate deliveries safely.
• 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 appropriate status codes:

• 2xx: Event received successfully.
• 429: Rate limiting. Include Retry-After header.
• 5xx: Server error requiring retry.

7. Support rate limiting headers

Supported rate-limiting header formats:

Supported rate-limiting headers

Header	Description
Retry-After	The webhook system supports these header formats: Seconds: Integer. Specifies seconds to wait. Retry-After: 120 HTTP date: Absolute timestamp in RFC 1123: Requirements for Internet Hosts -- Application and Support 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

Default behavior

When rate limiting is detected and no headers are present:

• Default wait time: 3 seconds.
• Subsequent retries: Exponential backoff is used.

8. Monitor and alert on webhook delivery failures

Optionally, monitor webhook delivery:

1. Log all received webhooks.
2. Track processing success/failure metrics.
3. Alert on repeated failures.

Support

For webhook integration support:

• Contact your Indeed integration team.
• See the CloudEvents specification.

 

Was this page helpful?